extra-desktop 0.3.3__tar.gz → 0.3.4__tar.gz

{extra_desktop-0.3.3/src/extra_desktop.egg-info → extra_desktop-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extra-desktop
-Version: 0.3.3
+Version: 0.3.4
 Summary: Flashless Linux, Windows & macOS Computer-Use Engine & Model Context Protocol (MCP) Server
 Author-email: AIYantra Engineering Team <engineering@yantraos.com>
 License-Expression: MIT
@@ -75,7 +75,9 @@ Dynamic: license-file
 
 ---
 
-## ✨ Why Extra?
+## What is Extra and Why Does It Exist?
+
+Extra is an open-source Computer Use protocol and Model Context Protocol (MCP) server developed by yantraOS. It bridges LLMs (including ChatGPT, Claude, Cursor, and Gemini) directly to physical desktop operating systems across Linux, macOS, and Windows. Extra replaces fragile vision-only screenshot loops with native OS accessibility trees and sub-3ms GPU frame streaming, delivering pixel-perfect clicking, instant typing, and up to 225× lower token costs.
 
 Today's AI assistants can write brilliant essays and code, but they are trapped inside a chat window. When you need them to click a button, open an app, organize your files, or input data into a spreadsheet, they can only give you text instructions.
 
@@ -89,7 +91,7 @@ It connects **Claude, Google Antigravity, Cursor, AGY**, or any autonomous agent
 
 ---
 
-## 💡 What You Can Ask Your AI To Do
+## What Can an AI Assistant Do With Extra?
 
 Once Extra is running, you can talk to your AI like a real human assistant sitting at your desk:
 
@@ -198,7 +200,9 @@ Or using native Python:
 
 ---
 
-## 🎯 How It Works Under The Hood
+## How Does Extra Work Under the Hood?
+
+Extra operates via a sovereign Dual-Plane Architecture that decouples visual perception from hardware actuation. For perception, Extra combines sub-3ms GPU frame capture (DirectX DXGI, Metal, Spectacle) with OS accessibility hierarchy inspection (COM UI Automation, AT-SPI2, Quartz). For actuation, Extra dispatches lossless kernel and Win32 hardware events with zero coordinate drift, guaranteeing deterministic control across all resolutions and display scaling factors.
 
 Extra is engineered from the ground up for speed, reliability, and token efficiency:
 

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/README.md

@@ -31,7 +31,9 @@
 
 ---
 
-## ✨ Why Extra?
+## What is Extra and Why Does It Exist?
+
+Extra is an open-source Computer Use protocol and Model Context Protocol (MCP) server developed by yantraOS. It bridges LLMs (including ChatGPT, Claude, Cursor, and Gemini) directly to physical desktop operating systems across Linux, macOS, and Windows. Extra replaces fragile vision-only screenshot loops with native OS accessibility trees and sub-3ms GPU frame streaming, delivering pixel-perfect clicking, instant typing, and up to 225× lower token costs.
 
 Today's AI assistants can write brilliant essays and code, but they are trapped inside a chat window. When you need them to click a button, open an app, organize your files, or input data into a spreadsheet, they can only give you text instructions.
 
@@ -45,7 +47,7 @@ It connects **Claude, Google Antigravity, Cursor, AGY**, or any autonomous agent
 
 ---
 
-## 💡 What You Can Ask Your AI To Do
+## What Can an AI Assistant Do With Extra?
 
 Once Extra is running, you can talk to your AI like a real human assistant sitting at your desk:
 
@@ -154,7 +156,9 @@ Or using native Python:
 
 ---
 
-## 🎯 How It Works Under The Hood
+## How Does Extra Work Under the Hood?
+
+Extra operates via a sovereign Dual-Plane Architecture that decouples visual perception from hardware actuation. For perception, Extra combines sub-3ms GPU frame capture (DirectX DXGI, Metal, Spectacle) with OS accessibility hierarchy inspection (COM UI Automation, AT-SPI2, Quartz). For actuation, Extra dispatches lossless kernel and Win32 hardware events with zero coordinate drift, guaranteeing deterministic control across all resolutions and display scaling factors.
 
 Extra is engineered from the ground up for speed, reliability, and token efficiency:
 

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "extra-desktop"
-version = "0.3.3"
+version = "0.3.4"
 description = "Flashless Linux, Windows & macOS Computer-Use Engine & Model Context Protocol (MCP) Server"
 readme = "README.md"
 requires-python = ">=3.10"

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/__init__.py

@@ -2,4 +2,4 @@
 Project Extra — Flashless Linux, Windows & macOS Computer-Use Engine & MCP Server.
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/cli.py

@@ -22,7 +22,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 try:
     from extra import __version__
 except Exception:
-    __version__ = "0.3.3"
+    __version__ = "0.3.4"
 
 from extra.core.capture import capture_screen
 from extra.core.focus import (
@@ -1058,6 +1058,53 @@ def cmd_audit(args) -> int:
         return 1
 
 
+def cmd_mode(args: argparse.Namespace) -> int:
+    """View or change the Extra automation execution speed mode."""
+    from extra.core.mode import (
+        ExecutionMode,
+        get_execution_mode,
+        set_execution_mode,
+        get_mode_config,
+    )
+
+    target_mode = getattr(args, "mode", None)
+    if not target_mode:
+        curr = get_execution_mode()
+        cfg = get_mode_config(curr)
+        print("\n" + "=" * 60)
+        print(f"  [Extra] EXECUTION MODE: {curr.value.upper()}")
+        print("=" * 60)
+        print(f"  * Active Profile          : {cfg.mode.value}")
+        print(f"  * Settle Delay Timeout    : {cfg.settle_timeout_sec}s")
+        print(f"  * Max Inspected Elements  : {cfg.max_inspect_elements}")
+        print(f"  * Compact UI Serialization: {cfg.compact_ui}")
+        print(f"  * Sleep Scale Factor      : {cfg.sleep_scale}x (max {cfg.max_sleep_ms}ms)")
+        print(f"  * Proactive Memory Recall : {cfg.proactive_memory_recall}")
+        print(f"  * Dual-Plane Verification : {cfg.dual_plane_verification}")
+        print("-" * 60)
+        print("  Available Modes:")
+        print("    - turbo    (low, fast)      : Sub-50ms dispatch, 0ms settle, <800B UI")
+        print("    - balanced (medium, default): ~15ms settle, balanced UI & safety gates")
+        print("    - smart    (high, verify)   : Full SOUL visual critic & memory recall")
+        print("-" * 60)
+        print("  Usage: extra mode <turbo|balanced|smart> or extra modeset <mode>\n")
+        return 0
+
+    try:
+        resolved = ExecutionMode.from_string(target_mode)
+    except Exception as e:
+        print(f"Error: Invalid mode '{target_mode}': {e}", file=sys.stderr)
+        return 1
+
+    cfg = set_execution_mode(resolved, persist=True)
+    print(f"\n[Extra] Execution mode set to: {resolved.value.upper()} (saved to ~/.extra/config.json)")
+    print(f"  * Settle Timeout   : {cfg.settle_timeout_sec}s")
+    print(f"  * Sleep Scale      : {cfg.sleep_scale}x")
+    print(f"  * Compact UI       : {cfg.compact_ui}")
+    print(f"  * Proactive Recall : {cfg.proactive_memory_recall}\n")
+    return 0
+
+
 def check_first_run_consent() -> None:
     """Checks and prompts for first-run interactive telemetry consent."""
     from extra.core.metrics.config import (
@@ -1109,6 +1156,13 @@ def build_parser() -> argparse.ArgumentParser:
     )
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
+    # mode / modeset
+    mode_parser = subparsers.add_parser("mode", help="View or set the Extra automation speed mode (turbo, balanced, smart)")
+    mode_parser.add_argument("mode", nargs="?", default=None, help="Speed mode to activate: turbo (low/fast), balanced (medium/default), smart (high/deliberate)")
+
+    modeset_parser = subparsers.add_parser("modeset", help="Set the Extra automation speed mode (alias for 'extra mode')")
+    modeset_parser.add_argument("mode", nargs="?", default=None, help="Speed mode to activate: turbo (low/fast), balanced (medium/default), smart (high/deliberate)")
+
     # doctor
     doctor_parser = subparsers.add_parser("doctor", help="Run system health and capability diagnostics")
     doctor_parser.add_argument("--open", "-o", action="store_true", help="Open System Settings privacy panes if permissions missing")
@@ -1261,7 +1315,9 @@ def main() -> None:
     except Exception:
         pass
 
-    if args.command == "stats":
+    if args.command in ("mode", "modeset"):
+        sys.exit(cmd_mode(args))
+    elif args.command == "stats":
         sys.exit(cmd_stats(args))
     elif args.command == "dashboard":
         sys.exit(cmd_dashboard(args))

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/__init__.py

@@ -74,6 +74,13 @@ from extra.core.subtask import (
     SubtaskRunner,
     run_subtask,
 )
+from extra.core.mode import (
+    ExecutionMode,
+    ModeConfig,
+    get_execution_mode,
+    set_execution_mode,
+    get_mode_config,
+)
 from extra.core.soul import (
     DecisionType,
     SoulDecision,
@@ -156,4 +163,10 @@ __all__ = [
     "SubtaskResult",
     "SubtaskRunner",
     "run_subtask",
+    # Sovereign Execution Mode Controller
+    "ExecutionMode",
+    "ModeConfig",
+    "get_execution_mode",
+    "set_execution_mode",
+    "get_mode_config",
 ]

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/distiller.py

@@ -212,8 +212,9 @@ class UIDistiller:
             max_elements=max(max_elements * 4, 150),
         )
 
-        # 3. Filter, Prune, and Classify
-        filtered_elements = self._prune_and_filter(raw_elements, interactive_only=interactive_only)
+        # 3. Filter, Prune, and Classify (with strict window viewport boundary enforcement)
+        win_rect = win_info.rect if (win_info and win_info.rect and win_info.width > 10 and win_info.height > 10) else None
+        filtered_elements = self._prune_and_filter(raw_elements, interactive_only=interactive_only, window_rect=win_rect)
 
         # Determine default source
         plat_src = "uia_tier0"
@@ -357,12 +358,25 @@ class UIDistiller:
         self,
         elements: List[UIElement],
         interactive_only: bool = False,
+        window_rect: Optional[Tuple[int, int, int, int]] = None,
     ) -> List[UIElement]:
         """Prunes noisy container nodes, deduplicates overlapping elements, and drops offscreen items."""
         pruned: List[UIElement] = []
         seen_keys: Set[Tuple[int, int, str]] = set()
 
         for el in elements:
+            # Universal Viewport Boundary Check:
+            # Discard any element whose bounding box is strictly outside the target window viewport
+            if window_rect:
+                w_left, w_top, w_right, w_bottom = window_rect
+                b_left, b_top, b_right, b_bottom = el.bounding_box
+                if b_bottom <= w_top or b_top >= w_bottom or b_right <= w_left or b_left >= w_right:
+                    continue
+
+            # Fallback: Reject extreme negative-Y/X coordinates from virtualized Qt/Chromium containers
+            if el.bounding_box[1] < -8000 or el.bounding_box[0] < -8000:
+                continue
+
             c_type = el.control_type or "Unknown"
             name = (el.name or "").strip()
             auto_id = (el.automation_id or "").strip()
@@ -376,8 +390,9 @@ class UIDistiller:
             is_action = c_type in ACTION_CONTROL_TYPES
             is_info = c_type in INFO_CONTROL_TYPES
             is_container = c_type in CONTAINER_CONTROL_TYPES
+            has_stream = " | Buffer:" in name or getattr(el, "source", "") in ("text_pattern", "ocr")
 
-            if interactive_only and not (is_input or is_action):
+            if interactive_only and not (is_input or is_action or has_stream):
                 continue
 
             # Discard unnamed, non-interactive containers with no ID
@@ -490,14 +505,26 @@ class UIDistiller:
 
         return "\n".join(lines)
 
+    def _get_provenance_tag(self, el: UIElement) -> str:
+        """Determines the semantic provenance tag for the given element."""
+        src = str(getattr(el, "source", "uia") or "uia").lower()
+        if "ocr" in src:
+            return "[OCR]"
+        elif "txt" in src or "text_pattern" in src or " | Buffer:" in el.name:
+            return "[TXT]"
+        elif "soul" in src:
+            return "[SOUL]"
+        return "[UIA]"
+
     def _format_element_line(self, el: UIElement, include_coordinates: bool = True) -> str:
-        """Formats a single UI element bullet."""
+        """Formats a single UI element bullet with provenance."""
         name = f"'{el.name}'" if el.name else "(unnamed)"
         coord_str = f" [Center: {el.center[0]}, {el.center[1]}]" if include_coordinates else ""
         auto_id_str = f" (id: {el.automation_id})" if el.automation_id and el.automation_id != el.name else ""
         enabled_str = " (disabled)" if not el.is_enabled else ""
+        tag = self._get_provenance_tag(el)
 
-        return f"- [ID: {el.element_id}] {el.control_type}: {name}{auto_id_str}{enabled_str}{coord_str}"
+        return f"- {tag} [ID: {el.element_id}] {el.control_type}: {name}{auto_id_str}{enabled_str}{coord_str}"
 
     def _format_compact_action_rows(
         self, actions: List[UIElement], include_coordinates: bool = True, row_tolerance: int = 14
@@ -548,6 +575,25 @@ class UIDistiller:
                 f"Size: {work_surface['width']}x{work_surface['height']} | Center: ({work_surface['center'][0]},{work_surface['center'][1]})]"
             )
 
+        # Streams & Buffers (Terminals, Console stdout, Rich Documents, OCR Text)
+        terminal_buffers = []
+        stream_items = []
+        for el in elements:
+            src_tag = self._get_provenance_tag(el)
+            if src_tag in ("[TXT]", "[OCR]") or " | Buffer:" in el.name:
+                coords = f"({el.center[0]},{el.center[1]})" if include_coordinates else ""
+                stream_items.append(f"{src_tag} [{el.element_id}] {el.name}{coords}")
+            if " | Buffer:" in el.name:
+                clean_buf = el.name.split(" | Buffer:", 1)[1].strip()
+                lines = [l.strip() for l in clean_buf.splitlines() if l.strip()]
+                clean_lines = " \n ".join(lines)
+                terminal_buffers.append(f"[{el.element_id}] {clean_lines}")
+
+        if terminal_buffers:
+            parts.append("TERMINAL_BUFFER: " + " | ".join(terminal_buffers[:4]))
+        if stream_items:
+            parts.append("STREAMS: " + " | ".join(stream_items[:4]))
+
         info_items = [
             f"{el.name}" for el in elements
             if el.control_type in INFO_CONTROL_TYPES and el.name
@@ -596,6 +642,8 @@ class UIDistiller:
                     "id": el.element_id,
                     "type": el.control_type,
                     "name": el.name,
+                    "provenance": self._get_provenance_tag(el),
+                    "source": getattr(el, "source", "uia"),
                     "center": list(el.center) if include_coordinates else None,
                     "enabled": el.is_enabled,
                 }

extra_desktop-0.3.4/src/extra/core/mode.py

@@ -0,0 +1,153 @@
+"""
+Project Extra — Sovereign Execution Mode Controller
+Manages runtime acceleration profiles: 'turbo' (low latency), 'balanced' (medium), and 'smart' (high verification).
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+
+class ExecutionMode(str, Enum):
+    TURBO = "turbo"        # Fast / Fire-and-forget / Minimal delays (< 15ms)
+    BALANCED = "balanced"  # Default / Adaptive SOUL settle / Compact UI (~100ms)
+    SMART = "smart"        # Full closed-loop verification / UIA + Pixel diffing / Memory recall (~400ms)
+
+    @classmethod
+    def from_string(cls, val: Union[str, ExecutionMode]) -> ExecutionMode:
+        if isinstance(val, ExecutionMode):
+            return val
+        s = str(val).strip().lower()
+        if s in ("turbo", "fast", "low", "lightning", "speed", "l"):
+            return cls.TURBO
+        if s in ("smart", "high", "deep", "full", "verify", "safe", "h"):
+            return cls.SMART
+        return cls.BALANCED
+
+
+@dataclass
+class ModeConfig:
+    mode: ExecutionMode
+    auto_settle: bool
+    settle_timeout_sec: float
+    max_inspect_elements: int
+    compact_ui: bool
+    strip_heavy_attributes: bool
+    sleep_scale: float
+    max_sleep_ms: float
+    proactive_memory_recall: bool
+    dual_plane_verification: bool
+
+    @property
+    def name(self) -> ExecutionMode:
+        return self.mode
+
+    def scale_sleep(self, duration_ms: float) -> float:
+        """Scales requested sleep duration (in milliseconds) according to mode profile."""
+        scaled = float(duration_ms) * self.sleep_scale
+        return min(scaled, self.max_sleep_ms)
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["mode"] = self.mode.value
+        return d
+
+
+MODE_PROFILES: Dict[ExecutionMode, ModeConfig] = {
+    ExecutionMode.TURBO: ModeConfig(
+        mode=ExecutionMode.TURBO,
+        auto_settle=False,
+        settle_timeout_sec=0.5,
+        max_inspect_elements=10,
+        compact_ui=True,
+        strip_heavy_attributes=True,
+        sleep_scale=0.05,
+        max_sleep_ms=50.0,
+        proactive_memory_recall=False,
+        dual_plane_verification=False,
+    ),
+    ExecutionMode.BALANCED: ModeConfig(
+        mode=ExecutionMode.BALANCED,
+        auto_settle=True,
+        settle_timeout_sec=1.5,
+        max_inspect_elements=15,
+        compact_ui=True,
+        strip_heavy_attributes=True,
+        sleep_scale=0.5,
+        max_sleep_ms=500.0,
+        proactive_memory_recall=False,
+        dual_plane_verification=False,
+    ),
+    ExecutionMode.SMART: ModeConfig(
+        mode=ExecutionMode.SMART,
+        auto_settle=True,
+        settle_timeout_sec=4.0,
+        max_inspect_elements=30,
+        compact_ui=False,
+        strip_heavy_attributes=False,
+        sleep_scale=1.0,
+        max_sleep_ms=10000.0,
+        proactive_memory_recall=True,
+        dual_plane_verification=True,
+    ),
+}
+
+def _load_initial_mode() -> ExecutionMode:
+    """Loads default mode from EXTRA_SPEED_MODE env var or persistent ~/.extra/config.json."""
+    env_val = os.environ.get("EXTRA_SPEED_MODE")
+    if env_val:
+        return ExecutionMode.from_string(env_val)
+    try:
+        cfg_path = Path.home() / ".extra" / "config.json"
+        if cfg_path.exists():
+            with open(cfg_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                if isinstance(data, dict) and "speed_mode" in data:
+                    return ExecutionMode.from_string(data["speed_mode"])
+    except Exception:
+        pass
+    return ExecutionMode.BALANCED
+
+
+_active_mode: ExecutionMode = _load_initial_mode()
+
+
+def get_execution_mode() -> ExecutionMode:
+    """Returns currently active global ExecutionMode."""
+    return _active_mode
+
+
+def set_execution_mode(mode: Union[str, ExecutionMode], persist: bool = True) -> ModeConfig:
+    """Sets active ExecutionMode and persists to ~/.extra/config.json by default."""
+    global _active_mode
+    _active_mode = ExecutionMode.from_string(mode)
+    os.environ["EXTRA_SPEED_MODE"] = _active_mode.value
+    if persist:
+        try:
+            cfg_path = Path.home() / ".extra" / "config.json"
+            cfg_path.parent.mkdir(parents=True, exist_ok=True)
+            data: Dict[str, Any] = {}
+            if cfg_path.exists():
+                try:
+                    with open(cfg_path, "r", encoding="utf-8") as f:
+                        data = json.load(f)
+                except Exception:
+                    data = {}
+            data["speed_mode"] = _active_mode.value
+            with open(cfg_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+        except Exception:
+            pass
+    return MODE_PROFILES[_active_mode]
+
+
+def get_mode_config(mode: Optional[Union[str, ExecutionMode]] = None) -> ModeConfig:
+    """Returns ModeConfig for given mode, or active mode if None."""
+    if mode is not None:
+        resolved = ExecutionMode.from_string(mode)
+        return MODE_PROFILES[resolved]
+    return MODE_PROFILES[_active_mode]

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/platform/base.py

@@ -85,6 +85,7 @@ class UIElement:
     is_enabled: bool = True
     is_offscreen: bool = False
     raw_element: Any = None
+    source: str = "uia"
 
     @property
     def width(self) -> int:
@@ -106,6 +107,7 @@ class UIElement:
             "center": list(self.center),
             "is_enabled": self.is_enabled,
             "is_offscreen": self.is_offscreen,
+            "source": self.source,
         }
 
 

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/platform/linux/shell.py

@@ -312,6 +312,18 @@ def get_desktop_indexer() -> XDGDesktopIndexer:
 # ── Built-in Application Fallbacks & Semantic Registry ────────────────────────
 
 BUILTIN_APP_FALLBACKS: Dict[str, Dict[str, Any]] = {
+    # Clock & Timer
+    "clock": {
+        "candidates": ["gnome-clocks", "kclock", "alarm-clock-applet"],
+        "type": "bin",
+        "proc": "clocks",
+    },
+    "timer": {
+        "candidates": ["gnome-clocks", "kclock", "alarm-clock-applet"],
+        "type": "bin",
+        "proc": "clocks",
+    },
+
     # Calculator
     "calc": {
         "candidates": ["kcalc", "gnome-calculator", "galculator", "xcalc", "speedcrunch", "qalculate-gtk", "bc"],

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/platform/macos/shell.py

@@ -44,6 +44,10 @@ BUILTIN_MAC_APP_REGISTRY: Dict[str, Dict[str, str]] = {
     "vlc": {"target": "VLC", "bundle": "/Applications/VLC.app", "proc": "VLC", "type": "app"},
     "blender": {"target": "Blender", "bundle": "/Applications/Blender.app", "proc": "Blender", "type": "app"},
     "canva": {"target": "Canva", "bundle": "/Applications/Canva.app", "proc": "Canva", "type": "app"},
+    "clock": {"target": "Clock", "bundle": "/System/Applications/Clock.app", "proc": "Clock", "type": "app"},
+    "timer": {"target": "Clock", "bundle": "/System/Applications/Clock.app", "proc": "Clock", "type": "app"},
+    "calendar": {"target": "Calendar", "bundle": "/System/Applications/Calendar.app", "proc": "Calendar", "type": "app"},
+    "mail": {"target": "Mail", "bundle": "/System/Applications/Mail.app", "proc": "Mail", "type": "app"},
 }
 
 MAC_APP_REGISTRY: Dict[str, Dict[str, str]] = dict(BUILTIN_MAC_APP_REGISTRY)

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/platform/windows/focus.py

@@ -196,17 +196,18 @@ ALIAS_PROCESS_MAP: Dict[str, str] = _DynamicProcessMap()
 
 
 def _normalize_title(t: str) -> str:
-    """Normalizes title string by stripping zero-width and invisible control unicode chars."""
+    """Normalizes title string by stripping zero-width, bidirectional, and invisible control unicode chars."""
     if not t:
         return ""
-    return (
-        t.replace("\u200b", "")
-        .replace("\u200c", "")
-        .replace("\u200d", "")
-        .replace("\ufeff", "")
-        .strip()
-        .lower()
+    bad_chars = (
+        "\u200b", "\u200c", "\u200d", "\u200e", "\u200f",
+        "\u202a", "\u202b", "\u202c", "\u202d", "\u202e",
+        "\ufeff", "\ufffc", "\u00a0",
     )
+    res = t
+    for ch in bad_chars:
+        res = res.replace(ch, "")
+    return res.strip().lower()
 
 
 def find_window_by_title(
@@ -286,6 +287,39 @@ def find_window_by_title(
             break
         time.sleep(0.1)
 
+    # Tier 5: Minimized or Tray Window Fallback
+    # If standard visible lookup fails, check non-visible windows for process match.
+    # If a window exists (e.g. Telegram or WhatsApp docked to tray or minimized console),
+    # restore it into foreground visibility and return it.
+    if visible_only:
+        proc_target = None
+        try:
+            from extra.core.platform.windows.shell import APP_REGISTRY
+            reg_entry = APP_REGISTRY.get(q)
+            if reg_entry and "proc" in reg_entry:
+                proc_target = reg_entry["proc"].lower().rstrip(".exe")
+        except Exception:
+            pass
+        if not proc_target:
+            proc_target = q.rstrip(".exe")
+
+        all_wins = list_windows(visible_only=False)
+        for win in all_wins:
+            w_proc = win.process_name.lower().rstrip(".exe")
+            is_proc_match = (
+                w_proc == proc_target
+                or proc_target in w_proc
+                or (len(proc_target) > 3 and w_proc in proc_target)
+                or (proc_target in ("powershell", "pwsh", "cmd") and w_proc in ("windowsterminal", "openconsole"))
+            )
+            if is_proc_match and win.title:
+                try:
+                    win32gui.ShowWindow(win.hwnd, SW_RESTORE)
+                    time.sleep(0.1)
+                except Exception:
+                    pass
+                return win
+
     return None
 
 

{extra_desktop-0.3.3 → extra_desktop-0.3.4}/src/extra/core/platform/windows/shell.py

@@ -63,9 +63,19 @@ BUILTIN_APP_REGISTRY: Dict[str, Dict[str, str]] = {
     "mspaint": {"target": "mspaint.exe", "type": "exe", "proc": "mspaint.exe"},
     "photos": {"target": "ms-photos:", "type": "uri", "proc": "Photos.exe"},
     "store": {"target": "ms-windows-store:", "type": "uri", "proc": "WinStore.App.exe"},
+    "clock": {"target": "ms-clock:", "type": "uri", "proc": "ApplicationFrameHost.exe"},
+    "alarms": {"target": "ms-clock:", "type": "uri", "proc": "ApplicationFrameHost.exe"},
+    "timer": {"target": "ms-clock:", "type": "uri", "proc": "ApplicationFrameHost.exe"},
+    "stopwatch": {"target": "ms-clock:", "type": "uri", "proc": "ApplicationFrameHost.exe"},
+    "mail": {"target": "outlookmail:", "type": "uri", "proc": "HxOutlook.exe"},
+    "calendar": {"target": "outlookcal:", "type": "uri", "proc": "HxCalendar.exe"},
+    "camera": {"target": "microsoft.windows.camera:", "type": "uri", "proc": "WindowsCamera.exe"},
+    "weather": {"target": "msnweather:", "type": "uri", "proc": "Weather.exe"},
     "vlc": {"target": "vlc.exe", "type": "exe", "proc": "vlc.exe"},
     "blender": {"target": "blender.exe", "type": "exe", "proc": "blender.exe"},
     "canva": {"target": "canva.exe", "type": "exe", "proc": "canva.exe"},
+    "telegram": {"target": "Telegram.exe", "type": "exe", "proc": "Telegram.exe"},
+    "whatsapp": {"target": "WhatsApp.exe", "type": "exe", "proc": "WhatsApp.exe"},
 }
 
 APP_REGISTRY: Dict[str, Dict[str, str]] = dict(BUILTIN_APP_REGISTRY)
@@ -538,9 +548,14 @@ def launch_app(
                     matched_pid = win.process_id
                     break
                 # Or matches process name (including WindowsTerminal hosting console apps in Win11)
+                is_uwp_host = bool(expected_proc and expected_proc.lower() == "applicationframehost.exe")
+                proc_matches = bool(expected_proc and win.process_name.lower() == expected_proc.lower())
+                title_matches = bool(clean_app in win_title or (clean_app in ("clock", "timer", "alarms", "stopwatch") and "clock" in win_title))
+
                 if (
-                    (expected_proc and win.process_name.lower() == expected_proc.lower())
+                    (proc_matches and (not is_uwp_host or title_matches))
                     or (clean_app in ("powershell", "cmd", "terminal") and "terminal" in win.process_name.lower())
+                    or (title_matches and win_title not in EXCLUDED_SHELL_TITLES)
                 ):
                     matched_hwnd = win.hwnd
                     matched_title = win.title