Browser Integration

# Main browser namespace
browser.document: DOMDocument  # HTML document interface
browser.window: BrowserWindow   # Global window object  
browser.console: Console        # Browser console for logging
browser.self: Any              # Current execution context (window/worker)
browser.scope: dict            # Global Python scope

from browser import document, window, console

# DOM access
element = document["element-id"]
console.log("Hello from Python!")

# Window properties
current_url = window.location.href

def bind(element: Element, event: str, options: dict = None) -> Callable:
    """
    Event binding decorator for DOM elements.
    
    Args:
        element: Target DOM element or selector
        event: Event type ('click', 'input', 'keydown', etc.)
        options: Event listener options (capture, once, passive)
        
    Returns:
        Decorator function for event handler
        
    The decorated function receives the event object as its parameter.
    """

from browser import document, bind

@bind(document["my-button"], "click")
def handle_click(event):
    event.preventDefault()
    print("Button clicked!")

@bind(window, "resize")  
def handle_resize(event):
    print(f"Window resized: {window.innerWidth}x{window.innerHeight}")

# Event options
@bind(document["form"], "submit", {"once": True})
def handle_submit(event):
    event.preventDefault()
    # Handle form submission once

class ObjectStorage:
    """Dict-like interface for complex object storage with JSON serialization."""
    
    def __init__(self, storage: Storage):
        """
        Initialize with underlying storage (localStorage/sessionStorage).
        
        Args:
            storage: Browser storage object
        """
    
    def __getitem__(self, key: Any) -> Any: ...
    def __setitem__(self, key: Any, value: Any) -> None: ...
    def __delitem__(self, key: Any) -> None: ...
    def __contains__(self, key: Any) -> bool: ...
    
    def get(self, key: Any, default: Any = None) -> Any: ...
    def pop(self, key: Any, default: Any = None) -> Any: ...
    def keys(self) -> list: ...
    def values(self) -> list: ...
    def items(self) -> list: ...
    def clear(self) -> None: ...
    def __len__(self) -> int: ...

from browser import window
from browser.object_storage import ObjectStorage

# Create object storage wrapper
obj_storage = ObjectStorage(window.localStorage)

# Store complex objects
obj_storage["user"] = {"name": "John", "preferences": {"theme": "dark"}}
obj_storage[42] = ["list", "of", "items"]

# Retrieve objects
user = obj_storage["user"]  # Returns dict
items = obj_storage.get(42, [])  # Returns list

class DOMDocument:
    """HTML document interface."""
    def __getitem__(self, id: str) -> Element: ...
    def createElement(self, tag: str) -> Element: ...
    def createTextNode(self, text: str) -> TextNode: ...
    def querySelector(self, selector: str) -> Element: ...
    def querySelectorAll(self, selector: str) -> list[Element]: ...
    
    # Properties
    body: Element
    head: Element
    title: str

class BrowserWindow:
    """Global window object."""
    # Location and navigation
    location: Location
    history: History
    
    # Storage
    localStorage: Storage
    sessionStorage: Storage
    
    # Dimensions  
    innerWidth: int
    innerHeight: int
    
    # Methods
    def alert(self, message: str) -> None: ...
    def confirm(self, message: str) -> bool: ...
    def prompt(self, message: str, default: str = "") -> str: ...

class Console:
    """Browser console interface."""
    def log(self, *args) -> None: ...
    def error(self, *args) -> None: ...
    def warn(self, *args) -> None: ...
    def info(self, *args) -> None: ...
    def clear(self) -> None: ...

class Event:
    """Browser event object."""
    target: Element        # Event target element
    currentTarget: Element # Current event handler element
    type: str             # Event type
    
    def preventDefault(self) -> None: ...
    def stopPropagation(self) -> None: ...
    def stopImmediatePropagation(self) -> None: ...

@bind(element, "mouseenter mouseleave")
def handle_hover(event):
    if event.type == "mouseenter":
        element.style.backgroundColor = "yellow"
    else:
        element.style.backgroundColor = ""

@bind(document, "click")
def handle_clicks(event):
    if event.target.classList.contains("button"):
        handle_button_click(event)

@bind(element, "touchstart", {"passive": True})
def handle_touch(event):
    # Passive listener for better performance
    pass

@bind(element, "click", {"once": True, "capture": True})
def handle_once(event):
    # Handle event once in capture phase
    pass

class Template:
    """HTML template engine with Python integration."""
    
    def __init__(self, element: Element | str, callbacks: list[Callable] = None):
        """
        Initialize template for element.
        
        Args:
            element: DOM element or element ID string
            callbacks: List of callback functions for b-on event binding
        """
    
    def render(self, **kwargs) -> None:
        """
        Render template with data values.
        
        Args:
            **kwargs: Template variables as keyword arguments
        """
    
    def on(self, element: Element, event: str, callback: Callable) -> None:
        """
        Bind event handler with automatic re-rendering on data changes.
        
        Args:
            element: Target element
            event: Event type
            callback: Handler function(event, template)
        """

class ElementData:
    """Template data object with attribute access."""
    
    def to_dict(self) -> dict: ...
    def clone(self) -> dict: ...

class TemplateError(Exception):
    """Template processing errors."""

<!-- Python code blocks -->
<tr b-code="for item in items">
    <td>{item.name}</td>
    <td>{item.value}</td>
</tr>

<!-- Conditional rendering -->
<div b-code="if show_details">
    <p>Details: {description}</p>
</div>

<!-- Dynamic attributes -->
<option value="{name}" selected="{name == selected}">
    {display_name}
</option>

<!-- Event binding -->
<button b-on="click:increment">Count: {counter}</button>

<!-- Include sub-templates -->
<div b-include="menu.html"></div>

from browser import document
from browser.template import Template

def increment(event, template):
    template.data.counter += 1

def decrement(event, template):
    template.data.counter -= 1

# Create template with callbacks
template = Template(document["app"], [increment, decrement])

# Render with initial data
template.render(
    counter=0,
    items=[{"name": "Item 1", "value": 10}],
    show_details=True,
    selected="option1"
)