Container Tree Navigation

class Con:
    """
    Container representation with comprehensive properties and navigation methods.
    """
    # Core identification
    id: int  # Unique container ID
    name: str  # Container name
    type: str  # Container type (workspace, con, floating_con, etc.)
    num: int  # Workspace number (for workspace containers)
    
    # Layout and positioning  
    layout: str  # Layout type (splith, splitv, stacked, tabbed, etc.)
    orientation: str  # Container orientation
    percent: float  # Size percentage within parent
    rect: Rect  # Container rectangle (x, y, width, height)
    window_rect: Optional[Rect]  # Window rectangle within container (may be None)
    deco_rect: Optional[Rect]  # Decoration rectangle (may be None)
    geometry: Optional[Rect]  # Window geometry (may be None)
    
    # State properties
    urgent: bool  # Urgent state
    focused: bool  # Focus state
    focus: List[int]  # Focus stack (container IDs)
    sticky: bool  # Sticky state
    floating: bool  # Floating state
    fullscreen_mode: int  # Fullscreen mode (0=none, 1=output, 2=global)
    scratchpad_state: str  # Scratchpad state
    
    # Visual properties
    border: str  # Border style
    current_border_width: int  # Current border width in pixels
    
    # Window-specific properties
    window: int  # X11 window ID (if applicable)
    window_class: Optional[str]  # Window class name (may be None)
    window_instance: Optional[str]  # Window instance name (may be None)
    window_role: Optional[str]  # Window role (may be None)
    window_title: Optional[str]  # Window title text (may be None)
    
    # Tree structure
    nodes: List[Con]  # Child containers
    floating_nodes: List[Con]  # Floating child containers
    marks: List[str]  # Container marks
    
    # Sway-specific properties
    app_id: str  # Application ID (sway/wayland)
    pid: int  # Process ID
    visible: bool  # Visibility state
    representation: str  # Container representation string
    gaps: Optional[Gaps]  # Gap configuration (may be None)

def root(self) -> Con:
    """
    Get the root container of the tree.
    
    Returns:
    Con: root container at top of hierarchy
    """

def descendants(self) -> List[Con]:
    """
    Get all descendant containers recursively.
    
    Returns:
    List[Con]: all containers below this one in the tree
    """

def leaves(self) -> List[Con]:
    """
    Get all leaf containers (containers with no children).
    
    Returns:
    List[Con]: containers that have no child containers
    """

def workspaces(self) -> List[Con]:
    """
    Get all workspace containers in the tree.
    
    Returns:
    List[Con]: all containers of type 'workspace'
    """

def workspace(self) -> Optional[Con]:
    """
    Get the workspace container that contains this container.
    
    Returns:
    Optional[Con]: parent workspace container or None if not found
    """

def scratchpad(self) -> Optional[Con]:
    """
    Get the scratchpad container.
    
    Returns:
    Optional[Con]: scratchpad container for hidden windows or None if not found
    """

def find_focused(self) -> Optional[Con]:
    """
    Find the currently focused container in the tree.
    
    Returns:
    Optional[Con]: focused container or None if no focus
    """

def find_by_id(self, id: int) -> Optional[Con]:
    """
    Find container by unique ID.
    
    Parameters:
    - id: int, container ID to search for
    
    Returns:
    Optional[Con]: matching container or None if not found
    """

def find_by_window(self, window: int) -> Optional[Con]:
    """
    Find container by X11 window ID.
    
    Parameters:
    - window: int, X11 window ID to search for
    
    Returns:
    Optional[Con]: container containing the window or None
    """

def find_by_pid(self, pid: int) -> List[Con]:
    """
    Find containers by process ID (sway only).
    
    Parameters:
    - pid: int, process ID to search for
    
    Returns:
    List[Con]: containers belonging to the process
    """

def find_named(self, pattern: str) -> List[Con]:
    """
    Find containers by name pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against container names
    
    Returns:
    List[Con]: containers with names matching the pattern
    """

def find_titled(self, pattern: str) -> List[Con]:
    """
    Find containers by window title pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against window titles
    
    Returns:
    List[Con]: containers with titles matching the pattern
    """

def find_classed(self, pattern: str) -> List[Con]:
    """
    Find containers by window class pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against window classes
    
    Returns:
    List[Con]: containers with classes matching the pattern
    """

def find_instanced(self, pattern: str) -> List[Con]:
    """
    Find containers by window instance pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against window instances
    
    Returns:
    List[Con]: containers with instances matching the pattern
    """

def find_by_role(self, pattern: str) -> List[Con]:
    """
    Find containers by window role pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against window roles
    
    Returns:
    List[Con]: containers with roles matching the pattern
    """

def find_marked(self, pattern: str = ".*") -> List[Con]:
    """
    Find containers by mark pattern using regex.
    
    Parameters:
    - pattern: str, regular expression to match against marks (default matches all)
    
    Returns:
    List[Con]: containers with marks matching the pattern
    """

def find_fullscreen(self) -> List[Con]:
    """
    Find all fullscreen containers.
    
    Returns:
    List[Con]: containers currently in fullscreen mode
    """

def command(self, command: str) -> List[CommandReply]:
    """
    Execute i3/sway command on this container.
    
    Parameters:
    - command: str, command to execute (container will be implicitly focused)
    
    Returns:
    List[CommandReply]: results of command execution
    """

def command_children(self, command: str) -> Optional[List[CommandReply]]:
    """
    Execute i3/sway command on all child containers.
    
    Parameters:
    - command: str, command to execute on each child
    
    Returns:
    Optional[List[CommandReply]]: results of command execution for each child, or None if no children
    """

class Rect:
    """Rectangle representation for container positioning."""
    x: int  # X coordinate
    y: int  # Y coordinate  
    width: int  # Rectangle width
    height: int  # Rectangle height

class Gaps:
    """Gap configuration for containers with useless gaps."""
    inner: int  # Inner gap size
    outer: int  # Outer gap size
    left: Optional[int]  # Left outer gap (may be None)
    right: Optional[int]  # Right outer gap (may be None)
    top: Optional[int]  # Top outer gap (may be None)
    bottom: Optional[int]  # Bottom outer gap (may be None)