Window and Runtime Environment

Some documents assume a browsing environment — a window, a location, storage, events. This layer models those objects in pure Python so such documents can be processed server-side without a browser.

The Window Object

Window anchors the environment, with WindowEventLoop driving its event processing, and Screen, VisualViewport, and BarProp modelling display-related state. BrowsingContext ties a window to its document.

Navigation State

Location and History model the address and session history; Navigator reports environment identity, configurable via set_default_user_agent().

Events

The EventTarget interface with the Event family — CustomEvent, UIEvent, MouseEvent, KeyboardEvent, FocusEvent, InputEvent, PopStateEvent, HashChangeEvent, ErrorEvent — implements standards event dispatch. AbortController and AbortSignal provide cancellation.

Storage and Messaging

Storage models key-value web storage. MessageChannel, MessagePort, and BroadcastChannel cover message passing, with structured-clone helpers (clone_value) behind them.

Observers and Performance

IntersectionObserver and ResizeObserver (with their entry types) model observation APIs, while Performance, PerformanceEntry, and Console round out the runtime services scripts commonly touch.

Tips and Best Practices

Only touch this layer when processing documents that genuinely depend on environment state — parsing and styling never require it
Use set_default_user_agent() when downstream logic branches on Navigator identity
Wire AbortSignal into long-running processing for clean cancellation

Common Issues

Issue	Cause	Fix
Script expects window globals	Document authored for browsers	Provide the `Window` environment layer
Events never fire	No event loop driving dispatch	Use `WindowEventLoop`
User-agent-dependent branch misbehaves	Default UA string in effect	Set via `set_default_user_agent()`

FAQ

Do I need a Window to parse HTML?

No — the environment layer is optional; parsing, CSSOM, and layout are independent of it.

Which event types are modelled?

The standard family: UI, mouse, keyboard, focus, input, popstate, hashchange, error, and custom events, all dispatched through EventTarget.

Is web storage persistent?

Storage models the API surface for processing purposes; persistence is up to the embedding application.

API Reference Summary

Class/Method	Description
`Window`	Browsing environment anchor
`Location`	Address state
`History`	Session history
`EventTarget`	Event dispatch interface
`AbortController`	Cancellation controller
`IntersectionObserver`	Intersection observation
`set_default_user_agent`	Configure Navigator identity

Window and Runtime Environment