From 13c566ce033049712b85a2feb570bdce963c0433 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Thu, 4 Dec 2025 15:24:19 +0000
Subject: [PATCH 1/8] Update requirements.

---
 requirements.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/requirements.txt b/requirements.txt
index 3eaa631..6d18dce 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
-mkdocs-material==9.3.1
+mkdocs-material==9.6.15
+mkdocstrings-python==1.16.12
 mike==1.1.2
 setuptools

From 7aa230e97883f57628d6aa088d2f032955edbe86 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Thu, 4 Dec 2025 15:35:49 +0000
Subject: [PATCH 2/8] Add mkdocstrings and some extra meta-data to mkdocs.yml
 for site wide configuration.

---
 mkdocs.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index d62e421..19298e6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,6 @@
 site_name: PyScript
+site_author: The PyScript OSS Team
+site_description: PyScript - an open source platform for Python in the browser.
 
 theme:
     name: material
@@ -58,6 +60,7 @@ plugins:
       css_dir: css
       javascript_dir: js
       canonical_version: null
+  - mkdocstrings
 
 nav:
   - Home: index.md

From dd56141839465ec3ad935da25d0dcdcf4cc80bf5 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Thu, 4 Dec 2025 16:26:58 +0000
Subject: [PATCH 3/8] Autogenerate within markdown.

---
 docs/api.md | 1286 ++-------------------------------------------------
 1 file changed, 28 insertions(+), 1258 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 21327b0..8285846 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,1287 +1,57 @@
 # Built-in APIs
 
-PyScript makes available convenience objects, functions and attributes.
+## PyScript
 
-In Python this is done via the builtin `pyscript` module:
+::: pyscript
 
-```python title="Accessing the document object via the pyscript module"
-from pyscript import document
-```
+## Context
 
-In HTML this is done via `py-*` and `mpy-*` attributes (depending on the
-interpreter you're using):
+::: pyscript.context
 
-```html title="An example of a py-click handler"
-<button id="foo" py-click="handler_defined_in_python">Click me</button>
-```
+## Display
 
-These APIs will work with both Pyodide and Micropython in exactly the same way.
+::: pyscript.display
 
-!!! info
+## Events
 
-    Both Pyodide and MicroPython provide access to two further lower-level
-    APIs:
+::: pyscript.events
 
-    * Access to
-      [JavaScript's `globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)
-      via importing the `js` module: `import js` (now `js` is a proxy for 
-      `globalThis` in which all native JavaScript based browser APIs are
-      found).
-    * Access to interpreter specific versions of utilities and the foreign
-      function interface. Since these are different for each interpreter, and
-      beyond the scope of PyScript's own documentation, please check each
-      project's documentation
-      ([Pyodide](https://pyodide.org/en/stable/usage/api-reference.html) / 
-      [MicroPython](https://docs.micropython.org/en/latest/)) for details of
-      these lower-level APIs.
+## Fetch
 
-PyScript can run in two contexts: the main browser thread, or on a web worker.
-The following three categories of API functionality explain features that are
-common for both main thread and worker, main thread only, and worker only. Most
-features work in both contexts in exactly the same manner, but please be aware
-that some are specific to either the main thread or a worker context.
+::: pyscript.fetch
 
-## Common features
+## FFI
 
-These Python objects / functions are available in both the main thread and in
-code running on a web worker:
+::: pyscript.ffi
 
-### `pyscript.config`
+## Flatted
 
-A Python dictionary representing the configuration for the interpreter.
+::: pyscript.flatted
 
-```python title="Reading the current configuration."
-from pyscript import config
+## FS
 
+::: pyscript.fs
 
-# It's just a dict.
-print(config.get("files"))
-# This will be either "mpy" or "py" depending on the current interpreter.
-print(config["type"])
-```
+## Media
 
-!!! info
+::: pyscript.media
 
-    The `config` object will always include a `type` attribute set to either
-    `mpy` or `py`, to indicate which version of Python your code is currently
-    running in.
+## Storage
 
-!!! warning
+::: pyscript.storage
 
-    Changing the `config` dictionary at runtime has no effect on the actual
-    configuration.
+## Util
 
-    It's just a convenience to **read the configuration** at run time.
+::: pyscript.util
 
-### `pyscript.current_target`
+## Web
 
-A utility function to retrieve the unique identifier of the element used
-to display content. If the element is not a `<script>` and it already has
-an `id`, that `id` will be returned.
+::: pyscript.web
 
-```html title="The current_target utility"
-<!-- current_target(): explicit-id -->
-<mpy-script id="explicit-id">
-    from pyscript import display, current_target
-    display(f"current_target(): {current_target()}")
-</mpy-script>
+## WebSocket
 
-<!-- current_target(): mpy-0 -->
-<mpy-script>
-    from pyscript import display, current_target
-    display(f"current_target(): {current_target()}")
-</mpy-script>
+::: pyscript.websocket
 
-<!-- current_target(): mpy-1 -->
-<!-- creates right after the <script>:
-    <script-py id="mpy-1">
-        <div>current_target(): mpy-1</div>
-    </script-py>
--->
-<script type="mpy">
-    from pyscript import display, current_target
-    display(f"current_target(): {current_target()}")
-</script>
-```
+## Workers
 
-!!! Note
-
-    The return value of `current_target()` always references a visible element
-    on the page, **not** at the current `<script>` that is executing the code.
-
-    To reference the `<script>` element executing the code, assign it an `id`:
-
-    ```html
-    <script type="mpy" id="unique-id">...</script>
-    ```
-
-    Then use the standard `document.getElementById(script_id)` function to
-    return a reference to it in your code.
-
-### `pyscript.display`
-
-A function used to display content. The function is intelligent enough to
-introspect the object[s] it is passed and work out how to correctly display the
-object[s] in the web page based on the following mime types:
-
-* `text/plain` to show the content as text
-* `text/html` to show the content as *HTML*
-* `image/png` to show the content as `<img>`
-* `image/jpeg` to show the content as `<img>`
-* `image/svg+xml` to show the content as `<svg>`
-* `application/json` to show the content as *JSON*
-* `application/javascript` to put the content in `<script>` (discouraged)
-
-The `display` function takes a list of `*values` as its first argument, and has
-two optional named arguments:
-
-* `target=None` - the DOM element into which the content should be placed.
-  If not specified, the `target` will use the `current_script()` returned id
-  and populate the related dedicated node to show the content.
-* `append=True` - a flag to indicate if the output is going to be appended to
-  the `target`.
-
-There are some caveats:
-
-* When used in the main thread, the `display` function automatically uses
-  the current `<py-script>` or `<mpy-script>` tag as the `target` into which
-  the content will be displayed.
-* If the `<script>` tag has the `target` attribute, and is not a worker,
-  the element on the page with that ID (or which matches that selector)
-  will be used to display the content instead.
-* When used in a worker, the `display` function needs an explicit
-  `target="dom-id"` argument to identify where the content will be
-  displayed.
-* In both the main thread and worker, `append=True` is the default
-  behaviour.
-
-
-```html title="Various display examples"
-<!-- will produce
-    <py-script>PyScript</py-script>
--->
-<py-script worker>
-    from pyscript import display
-    display("PyScript", append=False)
-</py-script>
-
-<!-- will produce
-    <script type="py">...</script>
-    <script-py>PyScript</script-py>
--->
-<script type="py">
-    from pyscript import display
-    display("PyScript", append=False)
-</script>
-
-<!-- will populate <h1>PyScript</h1> -->
-<script type="py" target="my-h1">
-    from pyscript import display
-    display("PyScript", append=False)
-</script>
-<h1 id="my-h1"></h1>
-
-<!-- will populate <h2>PyScript</h2> -->
-<script type="py" worker>
-    from pyscript import display
-    display("PyScript", target="my-h2", append=False)
-</script>
-<h2 id="my-h2"></h2>
-```
-
-### `pyscript.document`
-
-On both main and worker threads, this object is a proxy for the web page's
-[document object](https://developer.mozilla.org/en-US/docs/Web/API/Document).
-The `document` is a representation of the
-[DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Using_the_Document_Object_Model)
-and can be used to read or manipulate the content of the web page.
-
-### `pyscript.fetch`
-
-A common task is to `fetch` data from the web via HTTP requests. The
-`pyscript.fetch` function provides a uniform way to achieve this in both
-Pyodide and MicroPython. It is closely modelled on the
-[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) found
-in browsers with some important Pythonic differences.
-
-The simple use case is to pass in a URL and `await` the response. If this
-request is in a function, that function should also be defined as `async`.
-
-```python title="A simple HTTP GET with pyscript.fetch"
-from pyscript import fetch
-
-
-response = await fetch("https://example.com")
-if response.ok:
-    data = await response.text()
-else:
-    print(response.status)
-```
-
-The object returned from an `await fetch` call will have attributes that
-correspond to the
-[JavaScript response object](https://developer.mozilla.org/en-US/docs/Web/API/Response).
-This is useful for getting response codes, headers and other metadata before
-processing the response's data.
-
-Alternatively, rather than using a double `await` (one to get the response, the
-other to grab the data), it's possible to chain the calls into a single
-`await` like this:
-
-```python title="A simple HTTP GET as a single await"
-from pyscript import fetch
-
-data = await fetch("https://example.com").text()
-```
-
-The following awaitable methods are available to you to access the data
-returned from the server:
-
-* `arrayBuffer()` returns a Python
-  [memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview) of
-  the response. This is equivalent to the
-  [`arrayBuffer()` method](https://developer.mozilla.org/en-US/docs/Web/API/Response/arrayBuffer)
-  in the browser based `fetch` API.
-* `blob()` returns a JavaScript
-  [`blob`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob)
-  version of the response. This is equivalent to the
-  [`blob()` method](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob)
-  in the browser based `fetch` API.
-* `bytearray()` returns a Python
-  [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)
-  version of the response.
-* `json()` returns a Python datastructure representing a JSON serialised
-  payload in the response.
-* `text()` returns a Python string version of the response.
-
-The underlying browser `fetch` API has
-[many request options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options)
-that you should simply pass in as keyword arguments like this:
-
-```python title="Supplying request options."
-from pyscript import fetch
-
-
-result = await fetch("https://example.com", method="POST", body="HELLO").text()
-```
-
-!!! Danger
-
-    You may encounter
-    [CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS)
-    errors (especially with reference to a missing
-    [Access-Control-Allow-Origin header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin).
-
-    This is a security feature of modern browsers where the site to which you
-    are making a request **will not process a request from a site hosted at
-    another domain**.
-
-    For example, if your PyScript app is hosted under `example.com` and you
-    make a request to `bbc.co.uk` (who don't allow requests from other domains)
-    then you'll encounter this sort of CORS related error.
-
-    There is nothing PyScript can do about this problem (it's a feature, not a
-    bug). However, you could use a pass-through proxy service to get around
-    this limitation (i.e. the proxy service makes the call on your behalf).
-
-### `pyscript.ffi`
-
-The `pyscript.ffi` namespace contains foreign function interface (FFI) methods
-that work in both Pyodide and MicroPython.
-
-#### `pyscript.ffi.create_proxy`
-
-A utility function explicitly for when a callback function is added via an
-event listener. It ensures the function still exists beyond the assignment of
-the function to an event. Should you not `create_proxy` around the callback
-function, it will be immediately garbage collected after being bound to the
-event.
-
-!!! warning
-
-    There is some technical complexity to this situation, and we have attempted
-    to create a mechanism where `create_proxy` is never needed.
-
-    *Pyodide* expects the created proxy to be explicitly destroyed when it's
-    not needed / used anymore. However, the underlying `proxy.destroy()` method
-    has not been implemented in *MicroPython* (yet).
-
-    To simplify this situation and automatically destroy proxies based on
-    JavaScript memory management (garbage collection) heuristics, we have
-    introduced an **experimental flag**:
-
-    ```toml
-    experimental_create_proxy = "auto"
-    ```
-
-    This flag ensures the proxy creation and destruction process is managed for
-    you. When using this flag you should never need to explicitly call
-    `create_proxy`.
-
-The technical details of how this works are
-[described here](../user-guide/ffi#create_proxy).
-
-#### `pyscript.ffi.to_js`
-
-A utility function to convert Python references into their JavaScript
-equivalents. For example, a Python dictionary is converted into a JavaScript
-object literal (rather than a JavaScript `Map`), unless a `dict_converter`
-is explicitly specified and the runtime is Pyodide.
-
-The technical details of how this works are [described here](../user-guide/ffi#to_js).
-
-### `pyscript.fs`
-
-!!! danger
-
-    This API only works in Chromium based browsers.
-
-An API for mounting the user's local filesystem to a designated directory in
-the browser's virtual filesystem. Please see
-[the filesystem](../user-guide/filesystem) section of the user-guide for more
-information.
-
-#### `pyscript.fs.mount`
-
-Mount a directory on the user's local filesystem into the browser's virtual
-filesystem. If no previous
-[transient user activation](https://developer.mozilla.org/en-US/docs/Glossary/Transient_activation)
-has taken place, this function will result in a minimalist dialog to provide
-the required transient user activation.
-
-This asynchronous function takes four arguments:
-
-* `path` (required) - indicating the location on the in-browser filesystem to
-  which the user selected directory from the local filesystem will be mounted.
-* `mode` (default: `"readwrite"`) - indicates how the code may interact with
-  the mounted filesystem. May also be just `"read"` for read-only access.
-* `id` (default: `"pyscript"`) - indicate a unique name for the handler
-  associated with a directory on the user's local filesystem. This allows users
-  to select different folders and mount them at the same path in the
-  virtual filesystem.
-* `root` (default: `""`) - a hint to the browser for where to start picking the
-  path that should be mounted in Python. Valid values are: `desktop`,
-  `documents`, `downloads`, `music`, `pictures` or `videos` as per
-  [web standards](https://developer.mozilla.org/en-US/docs/Web/API/Window/showDirectoryPicker#startin).
-
-```python title="Mount a local directory to the '/local' directory in the browser's virtual filesystem"
-from pyscript import fs
-
-
-# May ask for permission from the user, and select the local target.
-await fs.mount("/local")
-```
-
-If the call to `fs.mount` happens after a click or other transient event, the
-confirmation dialog will not be shown.
-
-```python title="Mounting without a transient event dialog."
-from pyscript import fs
-
-
-async def handler(event):
-    """
-    The click event that calls this handler is already a transient event.
-    """
-    await fs.mount("/local")
-
-
-my_button.onclick = handler
-```
-
-#### `pyscript.fs.sync`
-
-Given a named `path` for a mount point on the browser's virtual filesystem,
-asynchronously ensure the virtual and local directories are synchronised (i.e.
-all changes made in the browser's mounted filesystem, are propagated to the
-user's local filesystem).
-
-```python title="Synchronise the virtual and local filesystems."
-await fs.sync("/local")
-```
-
-#### `pyscript.fs.unmount`
-
-Asynchronously unmount the named `path` from the browser's virtual filesystem
-after ensuring content is synchronized. This will free up memory and allow you
-to re-use the path to mount a different directory.
-
-```python title="Unmount from the virtual filesystem."
-await fs.unmount("/local")
-```
-
-### `pyscript.js_modules`
-
-It is possible to [define JavaScript modules to use within your Python code](../user-guide/configuration#javascript-modules).
-
-Such named modules will always then be available under the
-`pyscript.js_modules` namespace.
-
-!!! warning
-
-    Please see the documentation (linked above) about restrictions and gotchas
-    when configuring how JavaScript modules are made available to PyScript.
-
-### `pyscript.media`
-
-The `pyscript.media` namespace provides classes and functions for interacting
-with media devices and streams in a web browser. This module enables you to work
-with cameras, microphones, and other media input/output devices directly from
-Python code.
-
-#### `pyscript.media.Device`
-
-A class that represents a media input or output device, such as a microphone,
-camera, or headset.
-
-```python title="Creating a Device object"
-from pyscript.media import Device, list_devices
-
-# List all available media devices
-devices = await list_devices()
-# Get the first available device
-my_device = devices[0]
-```
-
-The `Device` class has the following properties:
-
-* `id` - a unique string identifier for the represented device.
-* `group` - a string group identifier for devices belonging to the same physical device.
-* `kind` - an enumerated value: "videoinput", "audioinput", or "audiooutput".
-* `label` - a string describing the device (e.g., "External USB Webcam").
-
-The `Device` class also provides the following methods:
-
-##### `Device.load(audio=False, video=True)`
-
-A class method that loads a media stream with the specified options.
-
-```python title="Loading a media stream"
-# Load a video stream (default)
-stream = await Device.load()
-
-# Load an audio stream only
-stream = await Device.load(audio=True, video=False)
-
-# Load with specific video constraints
-stream = await Device.load(video={"width": 1280, "height": 720})
-```
-
-Parameters:
-* `audio` (bool, default: False) - Whether to include audio in the stream.
-* `video` (bool or dict, default: True) - Whether to include video in the
-  stream. Can also be a dictionary of video constraints.
-
-Returns:
-* A media stream object that can be used with HTML media elements.
-
-##### `get_stream()`
-
-An instance method that gets a media stream from this specific device.
-
-```python title="Getting a stream from a specific device"
-# Find a video input device
-video_devices = [d for d in devices if d.kind == "videoinput"]
-if video_devices:
-    # Get a stream from the first video device
-    stream = await video_devices[0].get_stream()
-```
-
-Returns:
-* A media stream object from the specific device.
-
-#### `pyscript.media.list_devices()`
-
-An async function that returns a list of all currently available media input and
-output devices.
-
-```python title="Listing all media devices"
-from pyscript.media import list_devices
-
-devices = await list_devices()
-for device in devices:
-    print(f"Device: {device.label}, Kind: {device.kind}")
-```
-
-Returns:
-* A list of `Device` objects representing the available media devices.
-
-!!! Note
-
-    The returned list will omit any devices that are blocked by the document
-    Permission Policy or for which the user has not granted permission.
-
-### Simple Example
-
-```python title="Basic camera access"
-from pyscript import document
-from pyscript.media import Device
-
-async def init_camera():
-    # Get a video stream
-    stream = await Device.load(video=True)
-    
-    # Set the stream as the source for a video element
-    video_el = document.getElementById("camera")
-    video_el.srcObject = stream
-    
-# Initialize the camera
-init_camera()
-```
-
-!!! warning
-
-    Using media devices requires appropriate permissions from the user.
-    Browsers will typically show a permission dialog when `list_devices()` or
-    `Device.load()` is called.
-
-### `pyscript.storage`
-
-The `pyscript.storage` API wraps the browser's built-in
-[IndexDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
-persistent storage in a synchronous Pythonic API.
-
-!!! info 
-
-    The storage API is persistent per user tab, page, or domain, in the same
-    way IndexedDB persists.
-
-    This API **is not** saving files in the interpreter's virtual file system
-    nor onto the user's hard drive.
-
-```python
-from pyscript import storage
-
-
-# Each store must have a meaningful name.
-store = await storage("my-storage-name")
-
-# store is a dictionary and can now be used as such.
-```
-
-The returned dictionary automatically loads the current state of the referenced
-IndexDB. All changes are automatically queued in the background.
-
-```python
-# This is a write operation.
-store["key"] = value
-
-# This is also a write operation (it changes the stored data).
-del store["key"]
-```
-
-Should you wish to be certain changes have been synchronized to the underlying
-IndexDB, just `await store.sync()`.
-
-Common types of value can be stored via this API: `bool`, `float`, `int`, `str`
-and `None`. In addition, data structures like `list`, `dict` and `tuple` can
-be stored.
-
-!!! warning
-
-    Because of the way the underlying data structure are stored in IndexDB,
-    a Python `tuple` will always be returned as a Python `list`.
-
-It is even possible to store arbitrary data via a `bytearray` or
-`memoryview` object. However, there is a limitation that **such values must be
-stored as a single key/value pair, and not as part of a nested data
-structure**.
-
-Sometimes you may need to modify the behaviour of the `dict` like object
-returned by `pyscript.storage`. To do this, create a new class that inherits
-from `pyscript.Storage`, then pass in your class to `pyscript.storage` as the
-`storage_class` argument:
-
-```python
-from pyscript import window, storage, Storage
-
-
-class MyStorage(Storage):
-
-    def __setitem__(self, key, value):
-        super().__setitem__(key, value)
-        window.console.log(key, value)
-        ...
-
-
-store = await storage("my-data-store", storage_class=MyStorage)
-
-# The store object is now an instance of MyStorage.
-```
-
-### `@pyscript/core/donkey`
-
-Sometimes you need an asynchronous Python worker ready and waiting to evaluate
-any code on your behalf. This is the concept behind the JavaScript "donkey". We
-couldn't think of a better way than "donkey" to describe something that is easy
-to understand and shoulders the burden without complaint. This feature
-means you're able to use PyScript without resorting to specialised
-`<script type="py">` style tags. It's just vanilla JavaScript.
-
-Simply `import { donkey } from '@pyscript/core/dist/core.js'` and automatically
-have both a *pyscript* module running on your page and a utility to bootstrap a
-terminal based worker to asynchronously evaluate any Python code as and when
-needed in the future.
-
-```js title="A donkey worker"
-import { donkey } from '@pyscript/core/dist/core.js';
-
-const {
-  process,              // process(code) code (visible in the terminal)
-  execute,              // execute(statement) in Python exec way
-  evaluate,             // evaluate(expression) in Python eval way
-  clear,                // clear() the terminal
-  reset,                // reset() the terminal (including colors)
-  kill,                 // kill() the worker forever
-} = await donkey({
-  type: 'py' || 'mpy',  // the Python interpreter to run
-  persistent: false,    // use `true` to track globals and locals
-  terminal: '',         // optionally set a target terminal container
-  config: {},           // the worker config (packages, files, etc.)
-});
-```
-
-By default PyScript creates a target terminal. If you don't want a terminal to
-appear on your page, use the `terminal` option to point to a CSS addressable
-container that is not visible (i.e. the target has `display: none`).
-
-### `@pyscript/core/dist/storage.js`
-
-The equivalent functionality based on the *JS* module can be found through our module.
-
-The goal is to be able to share the same database across different worlds (interpreters) and the functionality is nearly identical except there is no *class* to provide because the storage in *JS* is just a dictionary proxy that synchronizes behind the scene all read, write or delete operations.
-
-### `pyscript.web`
-
-The classes and references in this namespace provide a Pythonic way to interact
-with the DOM. An explanation for how to idiomatically use this API can be found
-[in the user guide](../user-guide/dom/#pyscriptweb)
-
-#### `pyscript.web.page`
-
-This object represents a web page. It has four attributes and two methods:
-
-* `html` - a reference to a Python object representing the [document's html](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html) root element.
-* `head` - a reference to a Python object representing the [document's head](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head).
-* `body` - a reference to a Python object representing the [document's body](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).
-* `title` - the page's [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) (usually displayed in the browser's title bar or a page's tab.
-* `find` - a method that takes a single [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)
-  argument and returns a collection of Python objects representing the matching
-  elements.
-* `append` - a shortcut for `page.body.append` (to add new elements to the
-  page).
-
-You may also shortcut the `find` method by enclosing a CSS selector in square
-brackets: `page["#my-thing"]`.
-
-These are provided as a convenience so you have several simple and obvious
-options for accessing and changing the content of the page.
-
-All the Python objects returned by these attributes and method are instances of
-classes relating to HTML elements defined in the `pyscript.web` namespace.
-
-#### `pyscript.web.*`
-
-There are many classes in this namespace. Each is a one-to-one mapping of any
-HTML element name to a Python class representing the HTML element of that
-name. Each Python class ensures only valid properties and attributes can be
-assigned, according to web standards.
-
-Usage of these classes is
-[explained in the user guide](../user-guide/dom/#pyscriptweb).
-
-!!! info 
-
-    The full list of supported element/class names is:
-
-    ```
-    grid
-    a, abbr, address, area, article, aside, audio
-    b, base, blockquote, body, br, button
-    canvas, caption, cite, code, col, colgroup
-    data, datalist, dd, del_, details, dialog, div, dl, dt
-    em, embed
-    fieldset, figcaption, figure, footer, form
-    h1, h2, h3, h4, h5, h6, head, header, hgroup, hr, html
-    i, iframe, img, input_, ins
-    kbd
-    label, legend, li, link
-    main, map_, mark, menu, meta, meter
-    nav
-    object_, ol, optgroup, option, output
-    p, param, picture, pre, progress
-    q
-    s, script, section, select, small, source, span, strong, style, sub, summary, sup
-    table, tbody, td, template, textarea, tfoot, th, thead, time, title, tr, track
-    u, ul
-    var, video
-    wbr
-    ``` 
-
-    These correspond to the standard
-    [HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)
-    with the caveat that `del_` and `input_` have the trailing underscore
-    (`_`) because they are also keywords in Python, and the `grid` is a custom
-    class for a `div` with a `grid` style `display` property.
-
-    All these classes ultimately derive from the
-    `pyscript.web.elements.Element` base class.
-
-In addition to properties defined by the HTML standard for each type of HTML
-element (e.g. `title`, `src` or `href`), all elements have the following
-properties and methods (in alphabetical order):
-
-* `append(child)` - add the `child` element to the element's children.
-* `children` - a collection containing the element's child elements (that it
-  contains).
-* `classes` - a set of CSS classes associated with the element.
-* `clone(clone_id=None)` - Make a clone of the element (and the underlying DOM
-  object), and assign it the optional `clone_id`.
-* `find(selector)` - use a CSS selector to find matching child elements.
-* `parent` - the element's parent element (that contains it).
-* `show_me` - scroll the element into view.
-* `style` - a dictionary of CSS style properties associated with the element.
-* `update(classes=None, style=None, **kwargs)` - update the element with the
-  specified classes (set), style (dict) and DOM properties (kwargs).
-* `_dom_element` - a reference to the proxy object that represents the
-  underlying native HTML element.
-
-!!! info
-
-    All elements, by virtue of inheriting from the base `Element` class, may
-    have the following properties:
-
-    ```
-    accesskey, autofocus, autocapitalize,
-    className, contenteditable,
-    draggable,
-    enterkeyhint,
-    hidden,
-    innerHTML, id,
-    lang,
-    nonce,
-    part, popover,
-    slot, spellcheck,
-    tabindex, text, title, translate,
-    virtualkeyboardpolicy
-    ```
-
-The `classes` set-like object has the following convenience functions:
-
-* `add(*class_names)` - add the class(es) to the element.
-* `contains(class_name)` - indicate if `class_name` is associated with the
-  element.
-* `remove(*class_names)` - remove the class(es) from the element.
-* `replace(old_class, new_class)` - replace the `old_class` with `new_class`.
-* `toggle(class_name)` - add a class if it is absent, or remove a class if it
-  is present.
-
-Elements that require options (such as the `datalist`, `optgroup` and `select`
-elements), can have options passed in when they are created:
-
-```python
-my_select = select_(option("apple", value=1), option("pear"))
-```
-
-Notice how options can be a tuple of two values (the name and associated value)
-or just the single name (whose associated value will default to the given
-name).
-
-It's possible to access and manipulate the `options` of the resulting elements:
-
-```python
-selected_option = my_select.options.selected
-my_select.options.remove(0)  # Remove the first option (in position 0).
-my_select.clear()
-my_select.options.add(html="Orange")
-```
-
-Finally, the collection of elements returned by `find` and `children` is
-iterable, indexable and sliceable:
-
-```python
-for child in my_element.children[10:]:
-    print(child.html)
-```
-
-Furthermore, four attributes related to all elements contained in the
-collection can be read (as a list) or set (applied to all contained elements):
-
-* `classes` - the list of classes associated with the elements.
-* `innerHTML` - the innerHTML of each element.
-* `style` - a dictionary like object for interacting with CSS style rules.
-* `value` - the `value` attribute associated with each element.
-
-### `pyscript.when`
-
-A Python decorator to indicate the decorated function should handle the
-specified events for selected elements.
-
-The decorator takes two parameters:
-
-* The `event_type` should be the name of the
-  [browser event to handle](https://developer.mozilla.org/en-US/docs/Web/Events)
-  as a string (e.g. `"click"`).
-* The `selector` should be a string containing a
-  [valid selector](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)
-  to indicate the target elements in the DOM whose events of `event_type` are
-  of interest.
-
-The following example has a button with an id of `my_button` and a decorated
-function that handles `click` events dispatched by the button.
-
-```html title="The HTML button"
-<button id="my_button">Click me!</button>
-```
-
-```python title="The decorated Python function to handle click events"
-from pyscript import when, display
-
-
-@when("click", "#my_button")
-def click_handler(event):
-    """
-    Event handlers get an event object representing the activity that raised
-    them.
-    """
-    display("I've been clicked!")
-
-### Or manually setting handler without a decorator
-when("click", "#my-button", handler=click_handler)
-```
-
-This functionality is related to the `py-*` or `mpy-*` [HTML attributes](#html-attributes).
-
-### `pyscript.window`
-
-On the main thread, this object is exactly the same as `import js` which, in
-turn, is a proxy of JavaScript's
-[globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)
-object.
-
-On a worker thread, this object is a proxy for the web page's
-[global window context](https://developer.mozilla.org/en-US/docs/Web/API/Window).
-
-!!! warning
-
-    The reference for `pyscript.window` is **always** a reference to the main
-    thread's global window context.
-
-    If you're running code in a worker this is **not the worker's own global
-    context**. A worker's global context is always reachable via `import js`
-    (the `js` object being a proxy for the worker's `globalThis`).
-
-### `pyscript.HTML`
-
-A class to wrap generic content and display it as un-escaped HTML on the page.
-
-```html title="The HTML class"
-<script type="mpy">
-    from pyscript import display, HTML
-
-    # Escaped by default:
-    display("<em>em</em>")  # &lt;em&gt;em&lt;/em&gt;
-</script>
-
-<script type="mpy">
-    from pyscript import display, HTML
-
-    # Un-escaped raw content inserted into the page:
-    display(HTML("<em>em</em>"))  # <em>em</em>
-</script>
-```
-
-### `pyscript.RUNNING_IN_WORKER`
-
-This constant flag is `True` when the current code is running within a
-*worker*. It is `False` when the code is running within the *main* thread.
-
-### `pyscript.WebSocket`
-
-If a `pyscript.fetch` results in a call and response HTTP interaction with a
-web server, the `pyscript.Websocket` class provides a way to use
-[websockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
-for two-way sending and receiving of data via a long term connection with a
-web server.
-
-PyScript's implementation, available in both the main thread and a web worker,
-closely follows the browser's own 
-[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) class.
-
-This class accepts the following named arguments:
-
-* A `url` pointing at the _ws_ or _wss_ address. E.g.:
-  `WebSocket(url="ws://localhost:5037/")`
-* Some `protocols`, an optional string or a list of strings as
-  [described here](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#parameters).
-
-The `WebSocket` class also provides these convenient static constants:
-
-* `WebSocket.CONNECTING` (`0`) - the `ws.readyState` value when a web socket
-  has just been created.
-* `WebSocket.OPEN` (`1`) - the `ws.readyState` value once the socket is open.
-* `WebSocket.CLOSING` (`2`) - the `ws.readyState` after `ws.close()` is
-  explicitly invoked to stop the connection.
-* `WebSocket.CLOSED` (`3`) - the `ws.readyState` once closed.
-
-A `WebSocket` instance has only 2 methods:
-
-* `ws.send(data)` - where `data` is either a string or a Python buffer,
-  automatically converted into a JavaScript typed array. This sends data via
-  the socket to the connected web server.
-* `ws.close(code=0, reason="because")` - which optionally accepts `code` and
-  `reason` as named arguments to signal some specific status or cause for
-  closing the web socket. Otherwise `ws.close()` works with the default
-  standard values.
-
-A `WebSocket` instance also has the fields that the JavaScript
-`WebSocket` instance will have:
-
-* [binaryType](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) -
-  the type of binary data being received over the WebSocket connection.
-* [bufferedAmount](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/bufferedAmount) -
-  a read-only property that returns the number of bytes of data that have been
-  queued using calls to `send()` but not yet transmitted to the network.
-* [extensions](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/extensions) -
-  a read-only property that returns the extensions selected by the server.
-* [protocol](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/protocol) -
-  a read-only property that returns the name of the sub-protocol the server
-  selected.
-* [readyState](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState) -
-  a read-only property that returns the current state of the WebSocket
-  connection as one of the `WebSocket` static constants (`CONNECTING`, `OPEN`,
-  etc...).
-* [url](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/url) -
-  a read-only property that returns the absolute URL of the `WebSocket`
-  instance.
-
-A `WebSocket` instance can have the following listeners. Directly attach
-handler functions to them. Such functions will always receive a single
-`event` object.
-
-* [onclose](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close_event) -
-  fired when the `WebSocket`'s connection is closed.
-* [onerror](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event) -
-  fired when the connection is closed due to an error.
-* [onmessage](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/message_event) -
-  fired when data is received via the `WebSocket`. If the `event.data` is a
-  JavaScript typed array instead of a string, the reference it will point
-  directly to a _memoryview_ of the underlying `bytearray` data.
-* [onopen](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event) -
-  fired when the connection is opened.
-
-The following code demonstrates a `pyscript.WebSocket` in action.
-
-```html
-<script type="mpy" worker>
-    from pyscript import WebSocket
-
-    def onopen(event):
-        print(event.type)
-        ws.send("hello")
-
-    def onmessage(event):
-        print(event.type, event.data)
-        ws.close()
-
-    def onclose(event):
-        print(event.type)
-
-    ws = WebSocket(url="ws://localhost:5037/")
-    ws.onopen = onopen
-    ws.onmessage = onmessage
-    ws.onclose = onclose
-</script>
-```
-
-!!! info
-
-    It's also possible to pass in any handler functions as named arguments when
-    you instantiate the `pyscript.WebSocket` class:
-
-    ```python
-    from pyscript import WebSocket
-
-
-    def onmessage(event):
-        print(event.type, event.data)
-        ws.close()
-
-
-    ws = WebSocket(url="ws://example.com/socket", onmessage=onmessage)
-    ```
-
-### `pyscript.js_import`
-
-If a JavaScript module is only needed under certain circumstances, we provide
-an asynchronous way to import packages that were not originally referenced in
-your configuration.
-
-```html title="A pyscript.js_import example."
-<script type="py">
-from pyscript import js_import, window
-
-escaper, = await js_import("https://esm.run/html-escaper")
-
-window.console.log(escaper)
-```
-
-The `js_import` call returns an asynchronous tuple containing the JavaScript
-modules referenced as string arguments.
-
-### `pyscript.py_import`
-
-!!! warning
-
-    **This is an experimental feature.**
-
-    Feedback and bug reports are welcome!
-
-If you have a lot of Python packages referenced in your configuration, startup
-performance may be degraded as these are downloaded.
-
-If a Python package is only needed under certain circumstances, we provide an
-asynchronous way to import packages that were not originally referenced in your
-configuration.
-
-```html title="A pyscript.py_import example."
-<script type="py">
-from pyscript import py_import
-
-matplotlib, regex, = await py_import("matplotlib", "regex")
-
-print(matplotlib, regex)
-</script>
-```
-
-The `py_import` call returns an asynchronous tuple containing the Python
-modules provided by the packages referenced as string arguments.
-
-## Main-thread only features
-
-### `pyscript.PyWorker`
-
-A class used to instantiate a new worker from within Python.
-
-!!! Note
-
-    Sometimes we disambiguate between interpreters through naming conventions
-    (e.g. `py` or `mpy`).
-
-    However, this class is always `PyWorker` and **the desired interpreter 
-    MUST be specified via a `type` option**. Valid values for the type of
-    interpreter are either `micropython` or `pyodide`.
-
-The following fragments demonstrate how to evaluate the file `worker.py` on a
-new worker from within Python.
-
-```python title="worker.py - the file to run in the worker."
-from pyscript import RUNNING_IN_WORKER, display, sync
-
-display("Hello World", target="output", append=True)
-
-# will log into devtools console
-print(RUNNING_IN_WORKER)  # True
-print("sleeping")
-sync.sleep(1)
-print("awake")
-```
-
-```python title="main.py - starts a new worker in Python."
-from pyscript import PyWorker
-
-# type MUST be either `micropython` or `pyodide`
-PyWorker("worker.py", type="micropython")
-```
-
-```html title="The HTML context for the worker."
-<script type="mpy" src="./main.py">
-<div id="output"></div>  <!-- The display target -->
-```
-
-!!! info
-
-    Sometimes code running on a worker gets stuck in an infinite loop and
-    becomes unresponsive. There are many complicated reasons why this might
-    happen, but when it does happen you likely want to break out of this
-    loop. This is where the `isStuck` and `notStuck` features come into play.
-
-    If you have code in the worker that could end up in an unresponsive
-    infinite loop, for example:
-
-    ```python
-    import time
-
-    while True:
-        time.sleep(1)
-        print("Stuck in a loop") 
-    ```
-
-    ...then you only need wrap this code in the worker like this:
-
-    ```python
-    import time
-    from pyscript import sync
-    is_stuck = sync.isStuck
-    break_loop = sync.notStuck
-
-    def is_not_stuck(condition):
-        if not condition and is_stuck():
-            # this is a must to reset the "stuck" state
-            break_loop()
-            # throw an error to get out of the loop
-            raise RuntimeError('Worker was stuck, but now it is unstuck')
-        return condition
-
-    while is_not_stuck(True):
-        time.sleep(1)
-        print("Stuck in a loop")
-    ```
-
-    From your code on the main thread you may have something like this:
-
-    ```python
-    from pyscript import PyWorker
-
-    w = PyWorker("sticky_code.py", type="micropython")
-
-    @when("click", "unstick_button")
-    def handle_unstick():
-        w.unstuck()
-    ```
-
-    This starts the worker with you code that could get into an infinite loop,
-    then defines a function that calls the `unstuck()` function on the worker
-    when a button on the UI is clicked.
-
-### `pyscript.workers`
-
-The `pyscript.workers` reference allows Python code in the main thread to
-easily access named workers (and their exported functionality).
-
-For example, the following Pyodide code may be running on a named worker
-(see the `name` attribute of the `script` tag):
-
-```html
-<script type="py" worker name="py-version">
-import sys
-
-def version():
-    return sys.version
-
-# define what to export to main consumers
-__export__ = ["version"]
-</script>
-```
-
-While over on the main thread, this fragment of MicroPython will be able to
-access the worker's `version` function via the `workers` reference:
-
-```html
-<script type="mpy">
-from pyscript import workers
-
-pyworker = await workers["py-version"]
-
-# print the pyodide version
-print(await pyworker.version())
-</script>
-```
-
-Importantly, the `workers` reference will **NOT** provide a list of
-known workers, but will only `await` for a reference to a named worker
-(resolving when the worker is ready). This is because the timing of worker
-startup is not deterministic.
-
-Should you wish to await for all workers on the page at load time, it's
-possible to loop over matching elements in the document like this:
-
-```html
-<script type="mpy">
-from pyscript import document, workers
-
-for el in document.querySelectorAll("[type='py'][worker][name]"):
-    await workers[el.getAttribute('name')]
-
-# ... rest of the code
-</script>
-```
-
-## Worker only features
-
-### `pyscript.sync`
-
-A function used to pass serializable data from workers to the main thread. 
-
-Imagine you have this code on the main thread:
-
-```python title="Python code on the main thread"
-from pyscript import PyWorker
-
-def hello(name="world"):
-    display(f"Hello, {name}")
-
-worker = PyWorker("./worker.py")
-worker.sync.hello = hello
-```
-
-In the code on the worker, you can pass data back to handler functions like
-this:
-
-```python title="Pass data back to the main thread from a worker"
-from pyscript import sync
-
-sync.hello("PyScript")
-```
-
-## HTML attributes
-
-As a convenience, and to ensure backwards compatibility, PyScript allows the
-use of inline event handlers via custom HTML attributes.
-
-!!! warning
-
-    This classic pattern of coding (inline event handlers) is no longer
-    considered good practice in web development circles.
-
-    We include this behaviour for historic reasons, but the folks at
-    Mozilla [have a good explanation](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#inline_event_handlers_%E2%80%94_dont_use_these)
-    of why this is currently considered bad practice.
-
-These attributes, expressed as `py-*` or `mpy-*` attributes of an HTML element,
-reference the name of a Python function to run when the event is fired. You
-should replace the `*` with the _actual name of an event_ (e.g. `py-click` or
-`mpy-click`). This is similar to how all
-[event handlers on elements](https://html.spec.whatwg.org/multipage/webappapis.html#event-handlers-on-elements,-document-objects,-and-window-objects)
-start with `on` in standard HTML (e.g. `onclick`). The rule of thumb is to
-simply replace `on` with `py-` or `mpy-` and then reference the name of a
-Python function.
-
-```html title="A py-click event on an HTML button element."
-<button py-click="handle_click" id="my_button">Click me!</button>
-```
-
-```python title="The related Python function."
-from pyscript import window
-
-
-def handle_click(event):
-    """
-    Simply log the click event to the browser's console.
-    """
-    window.console.log(event)    
-```
-
-Under the hood, the [`pyscript.when`](#pyscriptwhen) decorator is used to
-enable this behaviour.
-
-!!! note
-
-    In earlier versions of PyScript, the value associated with the attribute
-    was simply evaluated by the Python interpreter. This was unsafe:
-    manipulation of the attribute's value could have resulted in the evaluation
-    of arbitrary code.
-
-    This is why we changed to the current behaviour: just supply the name
-    of the Python function to be evaluated, and PyScript will do this safely.
+::: pyscript.workers

From 3822ff20fbcd4d28ddb5d4bf6e1ba243ecfac54b Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Thu, 4 Dec 2025 16:27:36 +0000
Subject: [PATCH 4/8] Grab the pyscript namespace from the referenced release,
 and put it somewhere the docs can find it.

---
 version-update.js | 57 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/version-update.js b/version-update.js
index c8f6d0b..a2e5165 100644
--- a/version-update.js
+++ b/version-update.js
@@ -24,3 +24,60 @@ const patch = directory => {
 };
 
 patch(join(__dirname, 'docs'));
+
+// Download and extract PyScript source code for the current version.
+const { execSync } = require('child_process');
+const { mkdtempSync, rmSync, cpSync } = require('fs');
+const { tmpdir } = require('os');
+
+const downloadFileSync = (url, destination) => {
+  // Use curl which is available on Mac and Linux.
+  try {
+    execSync(`curl -L -o "${destination}" "${url}"`, { 
+      stdio: 'ignore' 
+    });
+  } catch (error) {
+    throw new Error(`Download failed: ${error.message}`);
+  }
+};
+
+const updatePyScriptSource = () => {
+  const url = `https://github.com/pyscript/pyscript/archive/refs/tags/${version}.zip`;
+  const tempDir = mkdtempSync(join(tmpdir(), 'pyscript-'));
+  const zipPath = join(tempDir, `pyscript-${version}.zip`);
+  const targetDir = join(__dirname, 'pyscript');
+
+  try {
+    console.log(`Downloading PyScript ${version}...`);
+    downloadFileSync(url, zipPath);
+
+    console.log('Extracting archive...');
+    execSync(`unzip -q "${zipPath}" -d "${tempDir}"`);
+
+    const sourceDir = join(
+      tempDir,
+      `pyscript-${version}`,
+      'core',
+      'src',
+      'stdlib',
+      'pyscript'
+    );
+
+    if (!statSync(sourceDir, { throwIfNoEntry: false })?.isDirectory()) {
+      throw new Error(`Expected directory not found: ${sourceDir}`);
+    }
+
+    console.log('Copying PyScript stdlib files...');
+    cpSync(sourceDir, targetDir, { recursive: true, force: true });
+
+    console.log('PyScript source updated successfully.');
+  } catch (error) {
+    console.error('Error updating PyScript source:', error.message);
+    process.exit(1);
+  } finally {
+    console.log('Cleaning up temporary files...');
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+};
+
+updatePyScriptSource();

From d2d581cc0b4e60ac4d54fecbcf68c84b45d734c7 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Thu, 4 Dec 2025 16:29:15 +0000
Subject: [PATCH 5/8] Add latest version of the pyscript namespace from which
 the API docs can be generated.

---
 pyscript/__init__.py  |   64 ++
 pyscript/context.py   |  175 +++++
 pyscript/display.py   |  260 ++++++++
 pyscript/events.py    |  223 +++++++
 pyscript/fetch.py     |  218 +++++++
 pyscript/ffi.py       |  161 +++++
 pyscript/flatted.py   |  223 +++++++
 pyscript/fs.py        |  257 ++++++++
 pyscript/media.py     |  244 +++++++
 pyscript/storage.py   |  246 +++++++
 pyscript/util.py      |   77 +++
 pyscript/web.py       | 1410 +++++++++++++++++++++++++++++++++++++++++
 pyscript/websocket.py |  298 +++++++++
 pyscript/workers.py   |  191 ++++++
 14 files changed, 4047 insertions(+)
 create mode 100644 pyscript/__init__.py
 create mode 100644 pyscript/context.py
 create mode 100644 pyscript/display.py
 create mode 100644 pyscript/events.py
 create mode 100644 pyscript/fetch.py
 create mode 100644 pyscript/ffi.py
 create mode 100644 pyscript/flatted.py
 create mode 100644 pyscript/fs.py
 create mode 100644 pyscript/media.py
 create mode 100644 pyscript/storage.py
 create mode 100644 pyscript/util.py
 create mode 100644 pyscript/web.py
 create mode 100644 pyscript/websocket.py
 create mode 100644 pyscript/workers.py

diff --git a/pyscript/__init__.py b/pyscript/__init__.py
new file mode 100644
index 0000000..58e24bd
--- /dev/null
+++ b/pyscript/__init__.py
@@ -0,0 +1,64 @@
+"""
+This is the main `pyscript` namespace. It provides the primary Pythonic API
+for users to interact with PyScript features sitting on top of the browser's
+own API (https://developer.mozilla.org/en-US/docs/Web/API). It includes
+utilities for common activities such as displaying content, handling events,
+fetching resources, managing local storage, and coordinating with web workers.
+
+Some notes about the naming conventions and the relationship between various
+similar-but-different names found within this code base.
+
+`import pyscript`
+
+This package contains the main user-facing API offered by pyscript. All
+the names which are supposed be used by end users should be made
+available in pyscript/__init__.py (i.e., this file).
+
+`import _pyscript`
+
+This is an internal module implemented in JS. It is used internally by
+the pyscript package, **end users should not use it directly**. For its
+implementation, grep for `interpreter.registerJsModule("_pyscript",
+...)` in `core.js`.
+
+`import js`
+
+This is the JS `globalThis`, as exported by Pyodide and/or Micropython's
+foreign function interface (FFI). As such, it contains different things in
+the main thread or in a worker, as defined by web standards.
+
+`import pyscript.context`
+
+This submodule abstracts away some of the differences between the main
+thread and a worker. In particular, it defines `window` and `document`
+in such a way that these names work in both cases: in the main thread,
+they are the "real" objects, in a worker they are proxies which work
+thanks to [coincident](https://github.com/WebReflection/coincident).
+
+`from pyscript import window, document`
+
+These are just the `window` and `document` objects as defined by
+`pyscript.context`. This is the blessed way to access them from `pyscript`,
+as it works transparently in both the main thread and worker cases.
+"""
+
+from polyscript import lazy_py_modules as py_import
+from pyscript.context import (
+    RUNNING_IN_WORKER,
+    PyWorker,
+    config,
+    current_target,
+    document,
+    js_import,
+    js_modules,
+    sync,
+    window,
+)
+from pyscript.display import HTML, display
+from pyscript.fetch import fetch
+from pyscript.storage import Storage, storage
+from pyscript.websocket import WebSocket
+from pyscript.events import when, Event
+
+if not RUNNING_IN_WORKER:
+    from pyscript.workers import create_named_worker, workers
diff --git a/pyscript/context.py b/pyscript/context.py
new file mode 100644
index 0000000..b5d8490
--- /dev/null
+++ b/pyscript/context.py
@@ -0,0 +1,175 @@
+"""
+Execution context management for PyScript.
+
+This module handles the differences between running in the main browser thread
+versus running in a Web Worker, providing a consistent API regardless of the
+execution context.
+
+Key features:
+- Detects whether code is running in a worker or main thread. Read this via
+  `pyscript.context.RUNNING_IN_WORKER`.
+- Parses and normalizes configuration from `polyscript.config` and adds the
+  Python interpreter type via the `type` key in `pyscript.context.config`.
+- Provides appropriate implementations of `window`, `document`, and `sync`.
+- Sets up JavaScript module import system, including a lazy `js_import`
+  function.
+- Manages `PyWorker` creation.
+- Provides access to the current display target via
+  `pyscript.context.display_target`.
+
+Main thread context:
+- `window` and `document` are available directly.
+- `PyWorker` can be created to spawn worker threads.
+- `sync` is not available (raises `NotSupported`).
+
+Worker context:
+- `window` and `document` are proxied from main thread (if SharedArrayBuffer
+  available).
+- `PyWorker` is not available (raises `NotSupported`).
+- `sync` utilities are available for main thread communication.
+"""
+
+import json
+import sys
+
+import js
+from polyscript import config as _polyscript_config
+from polyscript import js_modules
+from pyscript.util import NotSupported
+
+# Detect execution context: True if running in a worker, False if main thread.
+RUNNING_IN_WORKER = not hasattr(js, "document")
+
+# Parse and normalize configuration from polyscript.
+config = json.loads(js.JSON.stringify(_polyscript_config))
+if isinstance(config, str):
+    config = {}
+
+# Detect and add Python interpreter type to config.
+if "MicroPython" in sys.version:
+    config["type"] = "mpy"
+else:
+    config["type"] = "py"
+
+
+class _JSModuleProxy:
+    """
+    Proxy for JavaScript modules imported via js_modules.
+
+    This allows Python code to import JavaScript modules using Python's
+    import syntax:
+
+    ```python
+    from pyscript.js_modules lodash import debounce
+    ```
+
+    The proxy lazily retrieves the actual JavaScript module when accessed.
+    """
+
+    def __init__(self, name):
+        """
+        Create a proxy for the named JavaScript module.
+        """
+        self.name = name
+
+    def __getattr__(self, field):
+        """
+        Retrieve a JavaScript object/function from the proxied JavaScript
+        module via the given `field` name.
+        """
+        # Avoid Pyodide looking for non-existent special methods.
+        if not field.startswith("_"):
+            return getattr(getattr(js_modules, self.name), field)
+        return None
+
+
+# Register all available JavaScript modules in Python's module system.
+# This enables: from pyscript.js_modules.xxx import yyy
+for module_name in js.Reflect.ownKeys(js_modules):
+    sys.modules[f"pyscript.js_modules.{module_name}"] = _JSModuleProxy(module_name)
+sys.modules["pyscript.js_modules"] = js_modules
+
+
+# Context-specific setup: Worker vs Main Thread.
+if RUNNING_IN_WORKER:
+    import polyscript
+
+    # PyWorker cannot be created from within a worker.
+    PyWorker = NotSupported(
+        "pyscript.PyWorker",
+        "pyscript.PyWorker works only when running in the main thread",
+    )
+
+    # Attempt to access main thread's window and document via SharedArrayBuffer.
+    try:
+        window = polyscript.xworker.window
+        document = window.document
+        js.document = document
+
+        # Create js_import function that runs imports on the main thread.
+        js_import = window.Function(
+            "return (...urls) => Promise.all(urls.map((url) => import(url)))"
+        )()
+
+    except:
+        # SharedArrayBuffer not available - window/document cannot be proxied.
+        sab_error_message = (
+            "Unable to use `window` or `document` in worker. "
+            "This requires SharedArrayBuffer support. "
+            "See: https://docs.pyscript.net/latest/faq/#sharedarraybuffer"
+        )
+        js.console.warn(sab_error_message)
+        window = NotSupported("pyscript.window", sab_error_message)
+        document = NotSupported("pyscript.document", sab_error_message)
+        js_import = None
+
+    # Worker-specific utilities for main thread communication.
+    sync = polyscript.xworker.sync
+
+    def current_target():
+        """
+        Get the current output target in worker context.
+        """
+        return polyscript.target
+
+else:
+    # Main thread context setup.
+    import _pyscript
+    from _pyscript import PyWorker as _PyWorker, js_import
+    from pyscript.ffi import to_js
+
+    def PyWorker(url, **options):
+        """
+        Create a Web Worker running Python code.
+
+        This spawns a new worker thread that can execute Python code
+        found at the `url`, independently of the main thread. The
+        `**options` can be used to configure the worker.
+
+        ```python
+        from pyscript import PyWorker
+
+        # Create a worker to run background tasks.
+        # (`type` MUST be either `micropython` or `pyodide`)
+        worker = PyWorker("./worker.py", type="micropython")
+        ```
+
+        PyWorker can only be created from the main thread, not from
+        within another worker.
+        """
+        return _PyWorker(url, to_js(options))
+
+    # Main thread has direct access to window and document.
+    window = js
+    document = js.document
+
+    # sync is not available in main thread (only in workers).
+    sync = NotSupported(
+        "pyscript.sync", "pyscript.sync works only when running in a worker"
+    )
+
+    def current_target():
+        """
+        Get the current output target in main thread context.
+        """
+        return _pyscript.target
diff --git a/pyscript/display.py b/pyscript/display.py
new file mode 100644
index 0000000..0af530a
--- /dev/null
+++ b/pyscript/display.py
@@ -0,0 +1,260 @@
+"""
+Display Pythonic content in the browser.
+
+This module provides the `display()` function for rendering Python objects
+in the web page. The function introspects objects to determine the appropriate
+MIME type and rendering method.
+
+Supported MIME types:
+
+    - `text/plain`: Plain text (HTML-escaped)
+    - `text/html`: HTML content
+    - `image/png`: PNG images as data URLs
+    - `image/jpeg`: JPEG images as data URLs
+    - `image/svg+xml`: SVG graphics
+    - `application/json`: JSON data
+    - `application/javascript`: JavaScript code (discouraged)
+
+The `display()` function uses standard Python representation methods
+(`_repr_html_`, `_repr_png_`, etc.) to determine how to render objects.
+Object can provide a `_repr_mimebundle_` method to specify preferred formats
+like this:
+
+```python
+def _repr_mimebundle_(self):
+    return {
+        "text/html": "<b>Bold HTML</b>",
+        "image/png": "<base64-encoded-png-data>",
+    }
+```
+
+Heavily inspired by IPython's rich display system. See:
+
+https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html
+"""
+
+import base64
+import html
+import io
+from collections import OrderedDict
+from pyscript.context import current_target, document, window
+from pyscript.ffi import is_none
+
+
+def _render_image(mime, value, meta):
+    """
+    Render image (`mime`) data (`value`) as an HTML img element with data URL.
+    Any `meta` attributes are added to the img tag.
+
+    Accepts both raw bytes and base64-encoded strings for flexibility.
+    """
+    if isinstance(value, bytes):
+        value = base64.b64encode(value).decode("utf-8")
+    attrs = "".join([f' {k}="{v}"' for k, v in meta.items()])
+    return f'<img src="data:{mime};base64,{value}"{attrs}>'
+
+
+# Maps MIME types to rendering functions.
+_MIME_TO_RENDERERS = {
+    "text/plain": lambda v, m: html.escape(v),
+    "text/html": lambda v, m: v,
+    "image/png": lambda v, m: _render_image("image/png", v, m),
+    "image/jpeg": lambda v, m: _render_image("image/jpeg", v, m),
+    "image/svg+xml": lambda v, m: v,
+    "application/json": lambda v, m: v,
+    "application/javascript": lambda v, m: f"<script>{v}<\\/script>",
+}
+
+
+# Maps Python representation methods to MIME types. This is an ordered dict
+# because the order defines preference when multiple methods are available,
+# and MicroPython's limited dicts don't preserve insertion order.
+_METHOD_TO_MIME = OrderedDict(
+    [
+        ("savefig", "image/png"),
+        ("_repr_png_", "image/png"),
+        ("_repr_jpeg_", "image/jpeg"),
+        ("_repr_svg_", "image/svg+xml"),
+        ("_repr_html_", "text/html"),
+        ("_repr_json_", "application/json"),
+        ("_repr_javascript_", "application/javascript"),
+        ("__repr__", "text/plain"),
+    ]
+)
+
+
+class HTML:
+    """
+    Wrap a string to render as unescaped HTML in `display()`. This is
+    necessary because plain strings are automatically HTML-escaped for safety:
+
+    ```python
+    from pyscript import HTML, display
+
+
+    display(HTML("<h1>Hello World</h1>"))
+    ```
+
+    Inspired by IPython.display.HTML.
+    """
+
+    def __init__(self, html):
+        self._html = html
+
+    def _repr_html_(self):
+        return self._html
+
+
+def _get_representation(obj, method):
+    """
+    Call the given representation `method` on an object (`obj`).
+
+    Handles special cases like matplotlib's `savefig`. Returns `None`
+    if the `method` doesn't exist.
+    """
+    if method == "__repr__":
+        return repr(obj)
+    if not hasattr(obj, method):
+        return None
+    if method == "savefig":
+        buf = io.BytesIO()
+        obj.savefig(buf, format="png")
+        buf.seek(0)
+        return base64.b64encode(buf.read()).decode("utf-8")
+    return getattr(obj, method)()
+
+
+def _get_content_and_mime(obj):
+    """
+    Returns the formatted raw content to be inserted into the DOM representing
+    the given object, along with the object's detected MIME type.
+
+    Returns a tuple of (html_string, mime_type).
+
+    Prefers _repr_mimebundle_ if available, otherwise tries individual
+    representation methods, falling back to __repr__ (with a warning in
+    the console).
+
+    Implements a subset of IPython's rich display system (mimebundle support,
+    etc...).
+    """
+    if isinstance(obj, str):
+        return html.escape(obj), "text/plain"
+    # Prefer an object's mimebundle.
+    mimebundle = _get_representation(obj, "_repr_mimebundle_")
+    if mimebundle:
+        if isinstance(mimebundle, tuple):
+            # Grab global metadata.
+            format_dict, global_meta = mimebundle
+        else:
+            format_dict, global_meta = mimebundle, {}
+        # Try to render using mimebundle formats.
+        for mime_type, output in format_dict.items():
+            if mime_type in _MIME_TO_RENDERERS:
+                meta = global_meta.get(mime_type, {})
+                # If output is a tuple, merge format-specific metadata.
+                if isinstance(output, tuple):
+                    output, format_meta = output
+                    meta.update(format_meta)
+                return _MIME_TO_RENDERERS[mime_type](output, meta), mime_type
+    # No mimebundle or no available renderers therein, so try individual
+    # methods.
+    for method, mime_type in _METHOD_TO_MIME.items():
+        if mime_type not in _MIME_TO_RENDERERS:
+            continue
+        output = _get_representation(obj, method)
+        if output is None:
+            continue
+        meta = {}
+        if isinstance(output, tuple):
+            output, meta = output
+        return _MIME_TO_RENDERERS[mime_type](output, meta), mime_type
+    # Ultimate fallback to repr with warning.
+    window.console.warn(
+        f"Object {type(obj).__name__} has no supported representation method. "
+        "Using __repr__ as fallback."
+    )
+    output = repr(obj)
+    return html.escape(output), "text/plain"
+
+
+def _write_to_dom(element, value, append):
+    """
+    Given an `element` and a `value`, write formatted content to the referenced
+    DOM element. If `append` is True, content is added to the existing content;
+    otherwise, the existing content is replaced.
+
+    Creates a wrapper `div` when appending multiple items to preserve
+    structure.
+    """
+    html_content, mime_type = _get_content_and_mime(value)
+    if not html_content.strip():
+        return
+    if append:
+        container = document.createElement("div")
+        element.append(container)
+    else:
+        container = element
+    if mime_type in ("application/javascript", "text/html"):
+        container.append(document.createRange().createContextualFragment(html_content))
+    else:
+        container.innerHTML = html_content
+
+
+def display(*values, target=None, append=True):
+    """
+    Display Python objects in the web page.
+
+    * `*values`: Python objects to display. Each object is introspected to
+      determine the appropriate rendering method.
+    * `target`: DOM element ID where content should be displayed. If `None`
+      (default), uses the current script tag's designated output area. This
+      can start with '#' (which will be stripped for compatibility).
+    * `append`: If `True` (default), add content to existing output. If
+      `False`, replace existing content before displaying.
+
+    When used in a worker, `display()` requires an explicit `target` parameter
+    to identify where content will be displayed. If used on the main thread,
+    it automatically uses the current `<script>` tag as the target. If the
+    script tag has a `target` attribute, that element will be used instead.
+
+    A ValueError is raised if a valid target cannot be found for the current
+    context.
+
+    ```python
+    from pyscript import display, HTML
+
+
+    # Display raw HTML.
+    display(HTML("<h1>Hello, World!</h1>"))
+
+    # Display in current script's output area.
+    display("Hello, World!")
+
+    # Display in a specific element.
+    display("Hello", target="my-div")
+
+    # Replace existing content (note the `#`).
+    display("New content", target="#my-div", append=False)
+
+    # Display multiple values in the default target.
+    display("First", "Second", "Third")
+    ```
+    """
+    if isinstance(target, str):
+        # There's a valid target.
+        target = target[1:] if target.startswith("#") else target
+    elif is_none(target):
+        target = current_target()
+    element = document.getElementById(target)
+    if is_none(element):
+        raise ValueError(f"Cannot find element with id='{target}' in the page.")
+    # If possible, use a script tag's target attribute.
+    if element.tagName == "SCRIPT" and hasattr(element, "target"):
+        element = element.target
+    # Clear before displaying all values when not appending.
+    if not append:
+        element.replaceChildren()
+    # Add each value.
+    for value in values:
+        _write_to_dom(element, value, append)
diff --git a/pyscript/events.py b/pyscript/events.py
new file mode 100644
index 0000000..925cd60
--- /dev/null
+++ b/pyscript/events.py
@@ -0,0 +1,223 @@
+"""
+Event handling for PyScript.
+
+This module provides two complementary systems:
+
+1. The `Event` class: A simple publish-subscribe pattern for custom events
+   within *your* Python code.
+
+2. The `@when` decorator: Connects Python functions to browser DOM events,
+   or instances of the `Event` class, allowing you to respond to user
+   interactions like clicks, key presses and form submissions, or to custom
+   events defined in your Python code.
+"""
+
+import asyncio
+import inspect
+from functools import wraps
+from pyscript.context import document
+from pyscript.ffi import create_proxy
+from pyscript.util import is_awaitable
+
+
+class Event:
+    """
+    A custom event that can notify multiple listeners when triggered.
+
+    Use this class to create your own event system within Python code.
+    Listeners can be either regular functions or async functions.
+
+    ```python
+    from pyscript.events import Event
+
+    # Create a custom event.
+    data_loaded = Event()
+
+    # Add a listener.
+    def on_data_loaded(result):
+        print(f"Data loaded: {result}")
+
+    data_loaded.add_listener(on_data_loaded)
+
+    # Time passes.... trigger the event.
+    data_loaded.trigger({"data": 123})
+    ```
+    """
+
+    def __init__(self):
+        self._listeners = []
+
+    def trigger(self, result):
+        """
+        Trigger the event and notify all listeners with the given result.
+        """
+        for listener in self._listeners:
+            if is_awaitable(listener):
+                asyncio.create_task(listener(result))
+            else:
+                listener(result)
+
+    def add_listener(self, listener):
+        """
+        Add a function to be called when this event is triggered.
+
+        The listener must be callable. It can be either a regular function
+        or an async function. Duplicate listeners are ignored.
+        """
+        if not callable(listener):
+            msg = "Listener must be callable."
+            raise ValueError(msg)
+        if listener not in self._listeners:
+            self._listeners.append(listener)
+
+    def remove_listener(self, *listeners):
+        """
+        Remove specified listeners. If none specified, remove all listeners.
+        """
+        if listeners:
+            for listener in listeners:
+                try:
+                    self._listeners.remove(listener)
+                except ValueError:
+                    pass  # Silently ignore listeners not in the list.
+        else:
+            self._listeners = []
+
+
+def when(event_type, selector=None):
+    """
+    A decorator to handle DOM events or custom Event objects.
+
+    For DOM events, specify the `event_type` (e.g. `"click"`) and a `selector`
+    for target elements. For custom `Event` objects, just pass the `Event`
+    instance as the `event_type`. It's also possible to pass a list of `Event`
+    objects. The `selector` is required only for DOM events. It should be a
+    CSS selector string, Element, ElementCollection, or list of DOM elements.
+
+    The decorated function can be either a regular function or an async
+    function. If the function accepts an argument, it will receive the event
+    object (for DOM events) or the Event's result (for custom events). A
+    function does not need to accept any arguments if it doesn't require them.
+
+    ```python
+    from pyscript import when, display
+
+    # Handle DOM events.
+    @when("click", "#my-button")
+    def handle_click(event):
+        display("Button clicked!")
+
+    # Handle custom events.
+    my_event = Event()
+
+    @when(my_event)
+    def handle_custom():  # No event argument needed.
+        display("Custom event triggered!")
+
+    # Handle multiple custom events.
+    another_event = Event()
+
+    def another_handler():
+        display("Another custom event handler.")
+
+    # Attach the same handler to multiple events but not as a decorator.
+    when([my_event, another_event])(another_handler)
+
+    # Trigger an Event instance from a DOM event via @when.
+    @when("click", "#my-button")
+    def handle_click(event):
+        another_event.trigger("Button clicked!")
+
+    # Stacked decorators also work.
+    @when("mouseover", "#my-div")
+    @when(my_event)
+    def handle_both(event):
+        display("Either mouseover or custom event triggered!")
+    ```
+    """
+    if isinstance(event_type, str):
+        # This is a DOM event to handle, so check and use the selector.
+        if not selector:
+            raise ValueError("Selector required for DOM event handling.")
+        elements = _get_elements(selector)
+        if not elements:
+            raise ValueError(f"No elements found for selector: {selector}")
+
+    def decorator(func):
+        wrapper = _create_wrapper(func)
+        if isinstance(event_type, Event):
+            # Custom Event - add listener.
+            event_type.add_listener(wrapper)
+        elif isinstance(event_type, list) and all(
+            isinstance(t, Event) for t in event_type
+        ):
+            # List of custom Events - add listener to each.
+            for event in event_type:
+                event.add_listener(wrapper)
+        else:
+            # DOM event - attach to all matched elements.
+            for element in elements:
+                element.addEventListener(event_type, create_proxy(wrapper))
+        return wrapper
+
+    return decorator
+
+
+def _get_elements(selector):
+    """
+    Convert various selector types into a list of DOM elements.
+    """
+    from pyscript.web import Element, ElementCollection
+
+    if isinstance(selector, str):
+        return list(document.querySelectorAll(selector))
+    elif isinstance(selector, Element):
+        return [selector._dom_element]
+    elif isinstance(selector, ElementCollection):
+        return [el._dom_element for el in selector]
+    elif isinstance(selector, list):
+        return selector
+    else:
+        return [selector]
+
+
+def _create_wrapper(func):
+    """
+    Create an appropriate wrapper for the given function.
+
+    The wrapper handles both sync and async functions, and respects whether
+    the function expects to receive event arguments.
+    """
+    # Get the original function if it's been wrapped. This avoids wrapper
+    # loops when stacking decorators.
+    original_func = func
+    while hasattr(original_func, "__wrapped__"):
+        original_func = original_func.__wrapped__
+    # Inspect the original function signature.
+    sig = inspect.signature(original_func)
+    accepts_args = bool(sig.parameters)
+    if is_awaitable(func):
+        if accepts_args:
+
+            async def wrapper(event):
+                return await func(event)
+
+        else:
+
+            async def wrapper(*args, **kwargs):
+                return await func()
+
+    else:
+        if accepts_args:
+            # Always create a new wrapper function to avoid issues with
+            # stacked decorators getting into an infinite loop.
+
+            def wrapper(event):
+                return func(event)
+
+        else:
+
+            def wrapper(*args, **kwargs):
+                return func()
+
+    return wraps(func)(wrapper)
diff --git a/pyscript/fetch.py b/pyscript/fetch.py
new file mode 100644
index 0000000..28cb4ad
--- /dev/null
+++ b/pyscript/fetch.py
@@ -0,0 +1,218 @@
+"""
+A Pythonic wrapper around JavaScript's fetch API.
+
+This module provides a Python-friendly interface to the browser's fetch API,
+returning native Python data types and supported directly awaiting the promise
+and chaining method calls directly on the promise.
+
+```python
+from pyscript.fetch import fetch
+url = "https://api.example.com/data"
+
+# Pattern 1: Await the response, then extract data.
+response = await fetch(url)
+data = await response.json()
+
+# Pattern 2: Chain method calls directly on the promise.
+data = await fetch(url).json()
+```
+"""
+
+import json
+import js
+from pyscript.util import as_bytearray
+
+
+class _FetchResponse:
+    """
+    Wraps a JavaScript Response object with Pythonic data extraction methods.
+
+    This wrapper ensures that data returned from fetch is, if possible, in
+    native Python types rather than JavaScript types.
+    """
+
+    def __init__(self, response):
+        self._response = response
+
+    def __getattr__(self, attr):
+        """
+        Provide access to underlying Response properties like ok, status, etc.
+        """
+        return getattr(self._response, attr)
+
+    async def arrayBuffer(self):
+        """
+        Get response body as a buffer (memoryview or bytes).
+
+        Returns a memoryview in MicroPython or bytes in Pyodide, representing
+        the raw binary data.
+        """
+        buffer = await self._response.arrayBuffer()
+        if hasattr(buffer, "to_py"):
+            # Pyodide conversion.
+            return buffer.to_py()
+        # MicroPython conversion.
+        return memoryview(as_bytearray(buffer))
+
+    async def blob(self):
+        """
+        Get response body as a JavaScript Blob object.
+
+        Returns the raw JS Blob for use with other JS APIs.
+        """
+        return await self._response.blob()
+
+    async def bytearray(self):
+        """
+        Get response body as a Python bytearray.
+
+        Returns a mutable bytearray containing the response data.
+        """
+        buffer = await self._response.arrayBuffer()
+        return as_bytearray(buffer)
+
+    async def json(self):
+        """
+        Parse response body as JSON and return Python objects.
+
+        Returns native Python dicts, lists, strings, numbers, etc.
+        """
+        return json.loads(await self.text())
+
+    async def text(self):
+        """
+        Get response body as a text string.
+        """
+        return await self._response.text()
+
+
+class _FetchPromise:
+    """
+    Wraps the fetch promise to enable direct method chaining.
+
+    This allows calling response methods directly on the fetch promise:
+    `await fetch(url).json()` instead of requiring two separate awaits.
+
+    This feels more Pythonic since it matches typical usage patterns
+    Python developers have got used to via libraries like `requests`.
+    """
+
+    def __init__(self, promise):
+        self._promise = promise
+        # To be resolved in the future via the setup() static method.
+        promise._response = None
+        # Add convenience methods directly to the promise.
+        promise.arrayBuffer = self.arrayBuffer
+        promise.blob = self.blob
+        promise.bytearray = self.bytearray
+        promise.json = self.json
+        promise.text = self.text
+
+    @staticmethod
+    def setup(promise, response):
+        """
+        Store the resolved response on the promise for later access.
+        """
+        promise._response = _FetchResponse(response)
+        return promise._response
+
+    async def _get_response(self):
+        """
+        Get the cached response, or await the promise if not yet resolved.
+        """
+        if not self._promise._response:
+            await self._promise
+        return self._promise._response
+
+    async def arrayBuffer(self):
+        response = await self._get_response()
+        return await response.arrayBuffer()
+
+    async def blob(self):
+        response = await self._get_response()
+        return await response.blob()
+
+    async def bytearray(self):
+        response = await self._get_response()
+        return await response.bytearray()
+
+    async def json(self):
+        response = await self._get_response()
+        return await response.json()
+
+    async def text(self):
+        response = await self._get_response()
+        return await response.text()
+
+
+def fetch(url, **options):
+    """
+    Fetch a resource from the network using a Pythonic interface.
+
+    This wraps JavaScript's fetch API, returning Python-native data types
+    and supporting both direct promise awaiting and method chaining.
+
+    The function takes a `url` and optional fetch `options` as keyword
+    arguments. The `options` correspond to the JavaScript fetch API's
+    RequestInit dictionary, and commonly include:
+
+    - `method`: HTTP method (e.g., `"GET"`, `"POST"`, `"PUT"` etc.)
+    - `headers`: Dict of request headers.
+    - `body`: Request body (string, dict for JSON, etc.)
+
+    See the MDN documentation for details:
+    https://developer.mozilla.org/en-US/docs/Web/API/RequestInit
+
+    The function returns a promise that resolves to a Response-like object
+    with Pythonic methods to extract data:
+
+    - `await response.json()` to get JSON as Python objects.
+    - `await response.text()` to get text data.
+    - `await response.bytearray()` to get raw data as a bytearray.
+    - `await response.arrayBuffer()` to get raw data as a memoryview or bytes.
+    - `await response.blob()` to get the raw JS Blob object.
+
+    It's also possible to chain these methods directly on the fetch promise:
+    `data = await fetch(url).json()`
+
+    The returned response object also exposes standard properties like
+    `ok`, `status`, and `statusText` for checking response status.
+
+    ```python
+    # Simple GET request.
+    response = await fetch("https://api.example.com/data")
+    data = await response.json()
+
+    # Method chaining.
+    data = await fetch("https://api.example.com/data").json()
+
+    # POST request with JSON.
+    response = await fetch(
+        "https://api.example.com/users",
+        method="POST",
+        headers={"Content-Type": "application/json"},
+        body=json.dumps({"name": "Alice"})
+    )
+    result = await response.json()
+
+    # Check response status codes.
+    response = await fetch("https://api.example.com/data")
+    if response.ok:
+        # Status in the range 200-299.
+        data = await response.json()
+    elif response.status == 404:
+        print("Resource not found")
+    else:
+        print(f"Error: {response.status} {response.statusText}")
+    ```
+    """
+    # Convert Python dict to JavaScript object.
+    js_options = js.JSON.parse(json.dumps(options))
+
+    # Setup response handler to wrap the result.
+    def on_response(response, *_):
+        return _FetchPromise.setup(promise, response)
+
+    promise = js.fetch(url, js_options).then(on_response)
+    _FetchPromise(promise)
+    return promise
diff --git a/pyscript/ffi.py b/pyscript/ffi.py
new file mode 100644
index 0000000..1100277
--- /dev/null
+++ b/pyscript/ffi.py
@@ -0,0 +1,161 @@
+"""
+Consistent Foreign Function Interface (FFI) utilities for PyScript.
+
+This module provides a unified FFI layer that works consistently across both
+Pyodide and MicroPython, and in worker or main thread contexts, abstracting
+away the differences in their JavaScript interop APIs.
+
+The following utilities work on both the main thread and in worker contexts:
+
+- `create_proxy`: Create a persistent JavaScript proxy of a Python function.
+- `to_js`: Convert Python objects to JavaScript objects.
+- `is_none`: Check if a value is Python `None` or JavaScript `null`.
+- `assign`: Merge objects (like JavaScript's `Object.assign`).
+
+The following utilities are specific to worker contexts:
+
+- `direct`: Mark objects for direct JavaScript access.
+- `gather`: Collect multiple values from worker contexts.
+- `query`: Query objects in worker contexts.
+
+More details of the `direct`, `gather`, and `query` utilities can be found
+here:
+
+https://github.com/WebReflection/reflected-ffi?tab=readme-ov-file#remote-extra-utilities
+"""
+
+try:
+    # Attempt to import Pyodide's FFI utilities.
+    import js
+    from pyodide.ffi import create_proxy as _cp
+    from pyodide.ffi import to_js as _py_tjs
+    from pyodide.ffi import jsnull
+
+    from_entries = js.Object.fromEntries
+
+    def _to_js_wrapper(value, **kw):
+        if "dict_converter" not in kw:
+            kw["dict_converter"] = from_entries
+        return _py_tjs(value, **kw)
+
+except:
+    # Fallback to jsffi for MicroPython.
+    from jsffi import create_proxy as _cp
+    from jsffi import to_js as _to_js_wrapper
+    import js
+
+    jsnull = js.Object.getPrototypeOf(js.Object.prototype)
+
+
+def create_proxy(func):
+    """
+    Create a persistent JavaScript proxy of a Python function.
+
+    This proxy allows JavaScript code to call the Python function
+    seamlessly, maintaining the correct context and argument handling.
+
+    This is especially useful when passing Python functions as callbacks
+    to JavaScript APIs (without `create_proxy`, the function would be
+    garbage collected after the declaration of the callback).
+
+    ```python
+    from pyscript import ffi
+    from pyscript import document
+
+    my_button = document.getElementById("my-button")
+
+    def py_callback(x):
+        print(f"Callback called with {x}")
+
+    my_button.addEventListener("click", ffi.create_proxy(py_callback))
+    ```
+    """
+    return _cp(func)
+
+
+def to_js(value, **kw):
+    """
+    Convert Python objects to JavaScript objects.
+
+    This ensures Python dicts become proper JavaScript objects rather
+    than Maps, which is more intuitive for most use cases.
+
+    Where required, the underlying to_js uses Object.fromEntries for dict
+    conversion.
+
+    ```python
+    from pyscript import ffi
+    import js
+
+    note = {
+        "body": "This is a notification",
+        "icon": "icon.png"
+    }
+
+    js.Notification.new("Hello!", ffi.to_js(note))
+    ```
+    """
+    return _to_js_wrapper(value, **kw)
+
+
+def is_none(value):
+    """
+    Check if a value is `None` or JavaScript `null`.
+
+    In Pyodide, JavaScript `null` is represented by the `jsnull` object,
+    so we check for both Python `None` and `jsnull`. This function ensures
+    consistent behavior across Pyodide and MicroPython for null-like
+    values.
+
+    ```python
+    from pyscript import ffi
+    import js
+
+    val1 = None
+    val2 = js.null
+    val3 = 42
+
+    print(ffi.is_none(val1))  # True
+    print(ffi.is_none(val2))  # True
+    print(ffi.is_none(val3))  # False
+    ```
+    """
+    return value is None or value is jsnull
+
+
+try:
+    # Worker context utilities from reflected-ffi.
+    # See https://github.com/WebReflection/reflected-ffi for more details.
+    from polyscript import ffi as _ffi
+
+    _assign = _ffi.assign
+
+    direct = _ffi.direct
+    gather = _ffi.gather
+    query = _ffi.query
+
+except:
+    # Fallback implementations for main thread context.
+    import js
+
+    _assign = js.Object.assign
+
+    direct = lambda source: source
+
+
+def assign(source, *args):
+    """
+    Merge JavaScript objects (like Object.assign).
+
+    Takes a target object and merges properties from one or more source
+    objects into it, returning the modified target.
+
+    ```python
+    obj = js.Object.new()
+    ffi.assign(obj, {"a": 1}, {"b": 2})
+    # obj now has properties a=1 and b=2
+    ```
+    """
+    for arg in args:
+        _assign(source, to_js(arg))
+    return source
diff --git a/pyscript/flatted.py b/pyscript/flatted.py
new file mode 100644
index 0000000..73fa82d
--- /dev/null
+++ b/pyscript/flatted.py
@@ -0,0 +1,223 @@
+"""
+Circular JSON parser for Python.
+
+This module is a Python implementation of the Flatted JavaScript library
+(https://www.npmjs.com/package/flatted), which provides a super light and
+fast way to serialize and deserialize JSON structures that contain circular
+references.
+
+Standard JSON cannot handle circular references - attempting to serialize an
+object that references itself will cause an error. Flatted solves this by
+transforming circular structures into a flat array format that can be safely
+serialized and later reconstructed.
+
+Common use cases:
+- Serializing complex object graphs with circular references
+- Working with DOM-like structures that contain parent/child references
+- Preserving object identity when serializing data structures
+
+```python
+from pyscript import flatted
+
+# Create a circular structure.
+obj = {"name": "parent"}
+obj["self"] = obj  # Circular reference!
+
+# Standard json.dumps would fail here.
+serialized = flatted.stringify(obj)
+
+# Reconstruct the original structure.
+restored = flatted.parse(serialized)
+assert restored["self"] is restored  # Circular reference preserved!
+```
+"""
+
+import json as _json
+
+
+class _Known:
+    def __init__(self):
+        self.key = []
+        self.value = []
+
+
+class _String:
+    def __init__(self, value):
+        self.value = value
+
+
+def _array_keys(value):
+    keys = []
+    i = 0
+    for _ in value:
+        keys.append(i)
+        i += 1
+    return keys
+
+
+def _object_keys(value):
+    keys = []
+    for key in value:
+        keys.append(key)
+    return keys
+
+
+def _is_array(value):
+    return isinstance(value, (list, tuple))
+
+
+def _is_object(value):
+    return isinstance(value, dict)
+
+
+def _is_string(value):
+    return isinstance(value, str)
+
+
+def _index(known, input, value):
+    input.append(value)
+    index = str(len(input) - 1)
+    known.key.append(value)
+    known.value.append(index)
+    return index
+
+
+def _loop(keys, input, known, output):
+    for key in keys:
+        value = output[key]
+        if isinstance(value, _String):
+            _ref(key, input[int(value.value)], input, known, output)
+
+    return output
+
+
+def _ref(key, value, input, known, output):
+    if _is_array(value) and value not in known:
+        known.append(value)
+        value = _loop(_array_keys(value), input, known, value)
+    elif _is_object(value) and value not in known:
+        known.append(value)
+        value = _loop(_object_keys(value), input, known, value)
+
+    output[key] = value
+
+
+def _relate(known, input, value):
+    if _is_string(value) or _is_array(value) or _is_object(value):
+        try:
+            return known.value[known.key.index(value)]
+        except:
+            return _index(known, input, value)
+
+    return value
+
+
+def _transform(known, input, value):
+    if _is_array(value):
+        output = []
+        for val in value:
+            output.append(_relate(known, input, val))
+        return output
+
+    if _is_object(value):
+        obj = {}
+        for key in value:
+            obj[key] = _relate(known, input, value[key])
+        return obj
+
+    return value
+
+
+def _wrap(value):
+    if _is_string(value):
+        return _String(value)
+
+    if _is_array(value):
+        i = 0
+        for val in value:
+            value[i] = _wrap(val)
+            i += 1
+
+    elif _is_object(value):
+        for key in value:
+            value[key] = _wrap(value[key])
+
+    return value
+
+
+def parse(value, *args, **kwargs):
+    """
+    Parse a Flatted JSON string and reconstruct the original structure.
+
+    This function takes a `value` containing a JSON string created by
+    Flatted's stringify() and reconstructs the original Python object,
+    including any circular references. The `*args` and `**kwargs` are passed
+    to json.loads() for additional customization.
+
+    ```python
+    from pyscript import flatted
+
+    # Parse a Flatted JSON string.
+    json_string = '[{"name": "1", "self": "0"}, "parent"]'
+    obj = flatted.parse(json_string)
+
+    # Circular references are preserved.
+    assert obj["self"] is obj
+    ```
+    """
+    json = _json.loads(value, *args, **kwargs)
+    wrapped = []
+    for value in json:
+        wrapped.append(_wrap(value))
+
+    input = []
+    for value in wrapped:
+        if isinstance(value, _String):
+            input.append(value.value)
+        else:
+            input.append(value)
+
+    value = input[0]
+
+    if _is_array(value):
+        return _loop(_array_keys(value), input, [value], value)
+
+    if _is_object(value):
+        return _loop(_object_keys(value), input, [value], value)
+
+    return value
+
+
+def stringify(value, *args, **kwargs):
+    """
+    Serialize a Python object to a Flatted JSON string.
+
+    This function converts `value`, a Python object (including those with
+    circular references), into a JSON string that can be safely transmitted
+    or stored. The resulting string can be reconstructed using Flatted's
+    parse(). The `*args` and `**kwargs` are passed to json.dumps() for
+    additional customization.
+
+    ```python
+    from pyscript import flatted
+
+    # Create an object with a circular reference.
+    parent = {"name": "parent", "children": []}
+    child = {"name": "child", "parent": parent}
+    parent["children"].append(child)
+
+    # Serialize it (standard json.dumps would fail here).
+    json_string = flatted.stringify(parent)
+
+    # Can optionally pretty-print via JSON indentation etc.
+    pretty = flatted.stringify(parent, indent=2)
+    ```
+    """
+    known = _Known()
+    input = []
+    output = []
+    i = int(_index(known, input, value))
+    while i < len(input):
+        output.append(_transform(known, input, input[i]))
+        i += 1
+    return _json.dumps(output, *args, **kwargs)
diff --git a/pyscript/fs.py b/pyscript/fs.py
new file mode 100644
index 0000000..58cfc4d
--- /dev/null
+++ b/pyscript/fs.py
@@ -0,0 +1,257 @@
+"""
+Filesystem mounting for Chromium-based browsers.
+
+This module provides an API for mounting directories from the user's local
+filesystem into the browser's virtual filesystem. This allows Python code
+running in the browser to read and write files on the user's local machine.
+
+**Important:** This API only works in Chromium-based browsers (Chrome, Edge,
+Opera, Brave, etc.) that support the File System Access API.
+
+For technical details of the underlying Chromium based API, see:
+
+https://wicg.github.io/file-system-access/
+
+The module maintains a `mounted` dictionary that tracks all currently mounted
+paths and their associated filesystem handles.
+
+```python
+from pyscript import fs, document, when
+
+# Mount a local directory to the `/local` mount point in the browser's
+# virtual filesystem (may prompt user for permission).
+await fs.mount("/local")
+
+# Alternatively, mount on a button click event. This is important because
+# if the call to `fs.mount` happens after a click or other transient event,
+# the confirmation dialog will not be shown.
+@when("click", "#mount-button")
+async def handler(event):
+    await fs.mount("/another_dir")
+
+# Work with files in the mounted directory as usual.
+with open("/local/example.txt", "w") as f:
+    f.write("Hello from PyScript!")
+
+# Ensure changes are written to local filesystem.
+await fs.sync("/local")
+
+# Clean up when done.
+await fs.unmount("/local")
+```
+"""
+
+import js
+from _pyscript import fs as _fs, interpreter
+from pyscript import window
+from pyscript.ffi import to_js
+from pyscript.context import RUNNING_IN_WORKER
+
+# Worker-specific imports.
+if RUNNING_IN_WORKER:
+    from pyscript.context import sync as sync_with_worker
+    from polyscript import IDBMap
+
+# Global dictionary tracking mounted paths and their filesystem handles.
+mounted = {}
+
+
+async def _check_permission(details):
+    """
+    Check if permission has been granted for a filesystem handler. Returns
+    the handler if permission is granted, otherwise None.
+    """
+    handler = details.handler
+    options = details.options
+    permission = await handler.queryPermission(options)
+    return handler if permission == "granted" else None
+
+
+async def mount(path, mode="readwrite", root="", id="pyscript"):
+    """
+    Mount a directory from the local filesystem to the virtual filesystem
+    at the specified `path` mount point. The `mode` can be "readwrite" or
+    "read" to specify access level. The `root` parameter provides a hint
+    for the file picker starting location. The `id` parameter allows multiple
+    distinct mounts at the same path.
+
+    On first use, the browser will prompt the user to select a directory
+    and grant permission.
+
+    ```python
+    from pyscript import fs
+
+    # Basic mount with default settings.
+    await fs.mount("/local")
+
+    # Mount with read-only access.
+    await fs.mount("/readonly", mode="read")
+
+    # Mount with a hint to start in Downloads folder.
+    await fs.mount("/downloads", root="downloads")
+
+    # Mount with a custom ID to track different directories.
+    await fs.mount("/project", id="my-project")
+    ```
+
+    If called during a user interaction (like a button click), the
+    permission dialog may be skipped if permission was previously granted.
+    """
+    js.console.warn("experimental pyscript.fs ⚠️")
+
+    # Check if path is already mounted with a different ID.
+    mount_key = f"{path}@{id}"
+    if path in mounted:
+        # Path already mounted - check if it's the same ID.
+        for existing_key in mounted.keys():
+            if existing_key.startswith(f"{path}@") and existing_key != mount_key:
+                raise ValueError(
+                    f"Path '{path}' is already mounted with a different ID. "
+                    f"Unmount it first or use a different path."
+                )
+
+    details = None
+    handler = None
+
+    options = {"id": id, "mode": mode}
+    if root != "":
+        options["startIn"] = root
+
+    if RUNNING_IN_WORKER:
+        fs_handler = sync_with_worker.storeFSHandler(mount_key, to_js(options))
+
+        # Handle both async and SharedArrayBuffer use cases.
+        if isinstance(fs_handler, bool):
+            success = fs_handler
+        else:
+            success = await fs_handler
+
+        if success:
+            idbm = IDBMap.new(_fs.NAMESPACE)
+            details = await idbm.get(mount_key)
+            handler = await _check_permission(details)
+            if handler is None:
+                # Force await in either async or sync scenario.
+                await js.Promise.resolve(sync_with_worker.getFSHandler(details.options))
+                handler = details.handler
+        else:
+            raise RuntimeError(_fs.ERROR)
+
+    else:
+        success = await _fs.idb.has(mount_key)
+
+        if success:
+            details = await _fs.idb.get(mount_key)
+            handler = await _check_permission(details)
+            if handler is None:
+                handler = await _fs.getFileSystemDirectoryHandle(details.options)
+        else:
+            js_options = to_js(options)
+            handler = await _fs.getFileSystemDirectoryHandle(js_options)
+            details = {"handler": handler, "options": js_options}
+            await _fs.idb.set(mount_key, to_js(details))
+
+    mounted[path] = await interpreter.mountNativeFS(path, handler)
+
+
+async def sync(path):
+    """
+    Synchronise the virtual and local filesystems for a mounted `path`.
+
+    This ensures all changes made in the browser's virtual filesystem are
+    written to the user's local filesystem, and vice versa.
+
+    ```python
+    from pyscript import fs
+
+    await fs.mount("/local")
+
+    # Make changes to files.
+    with open("/local/data.txt", "w") as f:
+        f.write("Important data")
+
+    # Ensure changes are written to local disk.
+    await fs.sync("/local")
+    ```
+
+    This is automatically called by unmount(), but you may want to call
+    it explicitly to ensure data persistence at specific points.
+    """
+    if path not in mounted:
+        raise KeyError(
+            f"Path '{path}' is not mounted. " f"Use fs.mount() to mount it first."
+        )
+    await mounted[path].syncfs()
+
+
+async def unmount(path):
+    """
+    Unmount a directory, specified by `path`, from the virtual filesystem.
+
+    This synchronises any pending changes and then removes the mount point,
+    freeing up memory. The `path` can be reused for mounting a different
+    directory.
+
+    ```python
+    from pyscript import fs
+
+    await fs.mount("/local")
+    # ... work with files ...
+    await fs.unmount("/local")
+
+    # Path can now be reused.
+    await fs.mount("/local", id="different-folder")
+    ```
+
+    This automatically calls sync() before unmounting to ensure no data
+    is lost.
+    """
+    if path not in mounted:
+        raise KeyError(f"Path '{path}' is not mounted. Cannot unmount.")
+
+    await sync(path)
+    interpreter._module.FS.unmount(path)
+    del mounted[path]
+
+
+async def revoke(path, id="pyscript"):
+    """
+    Revoke filesystem access permission and unmount for a given
+    `path` and `id` combination.
+
+    This removes the stored permission for accessing the user's local
+    filesystem at the specified path and ID. Unlike unmount(), which only
+    removes the mount point, revoke() also clears the permission so the
+    user will be prompted again on next mount.
+
+    ```python
+    from pyscript import fs
+
+    await fs.mount("/local", id="my-app")
+    # ... work with files ...
+
+    # Revoke permission (user will be prompted again next time).
+    revoked = await fs.revoke("/local", id="my-app")
+
+    if revoked:
+        print("Permission revoked successfully")
+    ```
+
+    After revoking, the user will need to grant permission again and
+    select a directory when mount() is called next time.
+    """
+    mount_key = f"{path}@{id}"
+
+    if RUNNING_IN_WORKER:
+        handler_exists = sync_with_worker.deleteFSHandler(mount_key)
+    else:
+        handler_exists = await _fs.idb.has(mount_key)
+        if handler_exists:
+            handler_exists = await _fs.idb.delete(mount_key)
+
+    if handler_exists:
+        interpreter._module.FS.unmount(path)
+        if path in mounted:
+            del mounted[path]
+
+    return handler_exists
diff --git a/pyscript/media.py b/pyscript/media.py
new file mode 100644
index 0000000..716331f
--- /dev/null
+++ b/pyscript/media.py
@@ -0,0 +1,244 @@
+"""
+Media device access for PyScript.
+
+This module provides classes and functions for interacting with media devices
+and streams in the browser, enabling you to work with cameras, microphones,
+and other media input/output devices directly from Python.
+
+Use this module for:
+
+- Accessing webcams for video capture.
+- Recording audio from microphones.
+- Enumerating available media devices.
+- Applying constraints to media streams (resolution, frame rate, etc.).
+
+
+```python
+from pyscript import document
+from pyscript.media import Device, list_devices
+
+# Get a video stream from the default camera.
+stream = await Device.request_stream(video=True)
+
+# Display in a video element.
+video = document.getElementById("my-video")
+video.srcObject = stream
+
+# Or list all available devices.
+devices = await list_devices()
+for device in devices:
+    print(f"{device.kind}: {device.label}")
+```
+
+Using media devices requires user permission. Browsers will show a
+permission dialog when accessing devices for the first time.
+"""
+
+from pyscript import window
+from pyscript.ffi import to_js
+
+
+class Device:
+    """
+    Represents a media input or output device.
+
+    This class wraps a browser MediaDeviceInfo object, providing Pythonic
+    access to device properties like ID, label, and kind (audio/video
+    input/output).
+
+    Devices are typically obtained via `list_devices()` rather than
+    constructed directly.
+
+    ```python
+    from pyscript.media import list_devices
+
+    # Get all available devices.
+    devices = await list_devices()
+
+    # Find video input devices (cameras).
+    cameras = [d for d in devices if d.kind == "videoinput"]
+
+    # Get a stream from a specific camera.
+    if cameras:
+        stream = await cameras[0].get_stream()
+    ```
+    """
+
+    def __init__(self, device):
+        """
+        Create a Device wrapper around a MediaDeviceInfo `device`.
+        """
+        self._device_info = device
+
+    @property
+    def id(self):
+        """
+        Unique identifier for this device.
+
+        This ID persists across sessions but is reset when the user clears
+        cookies. It's unique to the origin of the calling application.
+        """
+        return self._device_info.deviceId
+
+    @property
+    def group(self):
+        """
+        Group identifier for related devices.
+
+        Devices belonging to the same physical device (e.g., a monitor with
+        both a camera and microphone) share the same group ID.
+        """
+        return self._device_info.groupId
+
+    @property
+    def kind(self):
+        """
+        Device type: "videoinput", "audioinput", or "audiooutput".
+        """
+        return self._device_info.kind
+
+    @property
+    def label(self):
+        """
+        Human-readable description of the device.
+
+        Example: "External USB Webcam" or "Built-in Microphone".
+        """
+        return self._device_info.label
+
+    def __getitem__(self, key):
+        """
+        Support bracket notation for JavaScript interop.
+
+        Allows accessing properties via device["id"] syntax. Necessary
+        when Device instances are proxied to JavaScript.
+        """
+        return getattr(self, key)
+
+    @classmethod
+    async def request_stream(cls, audio=False, video=True):
+        """
+        Request a media stream with the specified constraints.
+
+        This is a class method that requests access to media devices matching
+        the given `audio` and `video` constraints. The browser will prompt the
+        user for permission if needed and return a `MediaStream` object that
+        can be assigned to video/audio elements.
+
+        Simple boolean constraints for `audio` and `video` can be used to
+        request default devices. More complex constraints can be specified as
+        dictionaries conforming to the MediaTrackConstraints interface. See:
+
+        https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+
+        ```python
+        from pyscript import document
+        from pyscript.media import Device
+
+        # Get default video stream.
+        stream = await Device.request_stream()
+
+        # Get stream with specific constraints.
+        stream = await Device.request_stream(
+            video={"width": 1920, "height": 1080}
+        )
+
+        # Get audio and video.
+        stream = await Device.request_stream(audio=True, video=True)
+
+        # Use the stream.
+        video_el = document.getElementById("camera")
+        video_el.srcObject = stream
+        ```
+
+        This method will trigger a browser permission dialog on first use.
+        """
+        options = {}
+        if isinstance(audio, bool):
+            options["audio"] = audio
+        elif isinstance(audio, dict):
+            # audio is a dict of constraints (sampleRate, echoCancellation etc...).
+            options["audio"] = audio
+        if isinstance(video, bool):
+            options["video"] = video
+        elif isinstance(video, dict):
+            # video is a dict of constraints (width, height etc...).
+            options["video"] = video
+        return await window.navigator.mediaDevices.getUserMedia(to_js(options))
+
+    @classmethod
+    async def load(cls, audio=False, video=True):
+        """
+        Deprecated: Use request_stream() instead.
+
+        This method is retained for backwards compatibility but will be
+        removed in a future release. Please use request_stream() instead.
+        """
+        return await cls.request_stream(audio=audio, video=video)
+
+    async def get_stream(self):
+        """
+        Get a media stream from this specific device.
+
+        ```python
+        from pyscript.media import list_devices
+
+        # List all devices.
+        devices = await list_devices()
+
+        # Find a specific camera.
+        my_camera = None
+        for device in devices:
+            if device.kind == "videoinput" and "USB" in device.label:
+                my_camera = device
+                break
+
+        # Get a stream from that specific camera.
+        if my_camera:
+            stream = await my_camera.get_stream()
+        ```
+
+        This will trigger a permission dialog if the user hasn't already
+        granted permission for this device type.
+        """
+        # Extract media type from device kind (e.g., "videoinput" -> "video").
+        media_type = self.kind.replace("input", "").replace("output", "")
+        # Request stream with exact device ID constraint.
+        options = {media_type: {"deviceId": {"exact": self.id}}}
+        return await self.request_stream(**options)
+
+
+async def list_devices():
+    """
+    List all available media input and output devices.
+
+    Returns a list of all media devices currently available to the browser,
+    such as microphones, cameras, and speakers.
+
+    ```python
+    from pyscript.media import list_devices
+
+    # Get all devices.
+    devices = await list_devices()
+
+    # Print device information.
+    for device in devices:
+        print(f"{device.kind}: {device.label} (ID: {device.id})")
+
+    # Filter for specific device types.
+    cameras = [d for d in devices if d.kind == "videoinput"]
+    microphones = [d for d in devices if d.kind == "audioinput"]
+    speakers = [d for d in devices if d.kind == "audiooutput"]
+    ```
+
+    The returned list will omit devices that are blocked by the document
+    Permission Policy (microphone, camera, speaker-selection) or for
+    which the user has not granted explicit permission.
+
+    For security and privacy, device labels may be empty strings until
+    permission is granted. See:
+
+    https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
+    """
+    device_infos = await window.navigator.mediaDevices.enumerateDevices()
+    return [Device(device_info) for device_info in device_infos]
diff --git a/pyscript/storage.py b/pyscript/storage.py
new file mode 100644
index 0000000..3a13f7e
--- /dev/null
+++ b/pyscript/storage.py
@@ -0,0 +1,246 @@
+"""
+Persistent browser storage with a Pythonic dict-like interface.
+
+This module wraps the browser's IndexedDB persistent storage to provide a
+familiar Python dictionary API. Data is automatically serialized and
+persisted, surviving page reloads and browser restarts.
+
+Storage is persistent per origin (domain), isolated between different sites
+for security. Browsers typically allow each origin to store up to 10-60% of
+total disk space, depending on browser and configuration.
+
+What this module provides:
+
+- Dict-like API (get, set, delete, iterate).
+- Automatic serialization of common Python types.
+- Background persistence with optional explicit `sync()`.
+- Support for custom `Storage` subclasses.
+
+```python
+from pyscript import storage
+
+# Create or open a named storage.
+my_data = await storage("user-preferences")
+
+# Use like a regular dictionary.
+my_data["theme"] = "dark"
+my_data["font_size"] = 14
+my_data["settings"] = {"notifications": True, "sound": False}
+
+# Changes are queued automatically.
+# To ensure immediate write, sync explicitly.
+await my_data.sync()
+
+# Read values (survives page reload).
+theme = my_data.get("theme", "light")
+```
+
+Common types are automatically serialized: bool, int, float, str, None,
+list, dict, tuple. Binary data (bytearray, memoryview) can be stored as
+single values but not nested in structures.
+
+Tuples are deserialized as lists due to IndexedDB limitations.
+
+Browsers typically allow 10-60% of total disk space per origin. Chrome
+and Edge allow up to 60%, Firefox up to 10 GiB (or 10% of disk, whichever
+is smaller). Safari varies by app type. These limits are unlikely to be
+reached in typical usage.
+"""
+
+from polyscript import storage as _polyscript_storage
+from pyscript.flatted import parse as _parse
+from pyscript.flatted import stringify as _stringify
+from pyscript.ffi import is_none
+
+
+def _convert_to_idb(value):
+    """
+    Convert a Python `value` to an IndexedDB-compatible format.
+
+    Values are serialized using Flatted (for circular reference support)
+    with type information to enable proper deserialization. It returns a
+    JSON string representing the serialized value.
+
+    Will raise a TypeError if the value type is not supported.
+    """
+    if is_none(value):
+        return _stringify(["null", 0])
+    if isinstance(value, (bool, float, int, str, list, dict, tuple)):
+        return _stringify(["generic", value])
+    if isinstance(value, bytearray):
+        return _stringify(["bytearray", list(value)])
+    if isinstance(value, memoryview):
+        return _stringify(["memoryview", list(value)])
+    raise TypeError(f"Cannot serialize type {type(value).__name__} for storage.")
+
+
+def _convert_from_idb(value):
+    """
+    Convert an IndexedDB `value` back to its Python representation.
+
+    Uses type information stored during serialization to reconstruct the
+    original Python type.
+    """
+    kind, data = _parse(value)
+
+    if kind == "null":
+        return None
+    if kind == "generic":
+        return data
+    if kind == "bytearray":
+        return bytearray(data)
+    if kind == "memoryview":
+        return memoryview(bytearray(data))
+    # Fallback for all other types.
+    return value
+
+
+class Storage(dict):
+    """
+    A persistent dictionary backed by browser IndexedDB.
+
+    This class provides a dict-like interface with automatic persistence.
+    Changes are queued for background writing, with optional explicit
+    synchronization via `sync()`.
+
+    Inherits from `dict`, so all standard dictionary methods work as expected.
+
+    ```python
+    from pyscript import storage
+
+    # Open a storage.
+    prefs = await storage("preferences")
+
+    # Use as a dictionary.
+    prefs["color"] = "blue"
+    prefs["count"] = 42
+
+    # Iterate like a dict.
+    for key, value in prefs.items():
+        print(f"{key}: {value}")
+
+    # Ensure writes complete immediately.
+    await prefs.sync()
+    ```
+
+    Sometimes you may need to subclass `Storage` to add custom behavior:
+
+    ```python
+    from pyscript import storage, Storage, window
+
+    class LoggingStorage(Storage):
+        def __setitem__(self, key, value):
+            window.console.log(f"Setting {key} = {value}")
+            super().__setitem__(key, value)
+
+    my_store = await storage("app-data", storage_class=LoggingStorage)
+    my_store["test"] = 123  # Logs to console.
+    ```
+    """
+
+    def __init__(self, store):
+        """
+        Create a Storage instance wrapping an IndexedDB `store` (a JS
+        proxy).
+        """
+        super().__init__(
+            {key: _convert_from_idb(value) for key, value in store.entries()}
+        )
+        self._store = store
+
+    def __delitem__(self, key):
+        """
+        Delete an item from storage via its `key`.
+
+        The deletion is queued for persistence. Use `sync()` to ensure
+        immediate completion.
+        """
+        self._store.delete(key)
+        super().__delitem__(key)
+
+    def __setitem__(self, key, value):
+        """
+        Set a `key` to a `value` in storage.
+
+        The change is queued for persistence. Use `sync()` to ensure
+        immediate completion. The `value` must be a supported type for
+        serialization.
+        """
+        self._store.set(key, _convert_to_idb(value))
+        super().__setitem__(key, value)
+
+    def clear(self):
+        """
+        Remove all items from storage.
+
+        The clear operation is queued for persistence. Use `sync()` to ensure
+        immediate completion.
+        """
+        self._store.clear()
+        super().clear()
+
+    async def sync(self):
+        """
+        Force immediate synchronization to IndexedDB.
+
+        By default, storage operations are queued and written asynchronously.
+        Call `sync()` when you need to guarantee data is persisted immediately,
+        such as before critical operations or page unload.
+
+        ```python
+        store = await storage("important-data")
+        store["critical_value"] = data
+
+        # Ensure it's written before proceeding.
+        await store.sync()
+        ```
+
+        This is a blocking operation that waits for IndexedDB to complete
+        the write.
+        """
+        await self._store.sync()
+
+
+async def storage(name="", storage_class=Storage):
+    """
+    Open or create persistent storage with a unique `name` and optional
+    `storage_class` (used to extend the default `Storage` based behavior).
+
+    Each storage is isolated by name within the current origin (domain).
+    If the storage doesn't exist, it will be created. If it does exist,
+    its current contents will be loaded.
+
+    This function returns a Storage instance (or custom subclass instance)
+    acting as a persistent dictionary. A ValueError is raised if `name` is
+    empty or not provided.
+
+    ```python
+    from pyscript import storage
+
+    # Basic usage.
+    user_data = await storage("user-profile")
+    user_data["name"] = "Alice"
+    user_data["age"] = 30
+
+    # Multiple independent storages.
+    settings = await storage("app-settings")
+    cache = await storage("api-cache")
+
+    # With custom Storage class.
+    class ValidatingStorage(Storage):
+        def __setitem__(self, key, value):
+            if not isinstance(key, str):
+                raise TypeError("Keys must be strings")
+            super().__setitem__(key, value)
+
+    validated = await storage("validated-data", ValidatingStorage)
+    ```
+
+    Storage names are automatically prefixed with "@pyscript/" to
+    namespace them within IndexedDB.
+    """
+    if not name:
+        raise ValueError("Storage name must be a non-empty string")
+
+    underlying_store = await _polyscript_storage(f"@pyscript/{name}")
+    return storage_class(underlying_store)
diff --git a/pyscript/util.py b/pyscript/util.py
new file mode 100644
index 0000000..bbc1c35
--- /dev/null
+++ b/pyscript/util.py
@@ -0,0 +1,77 @@
+"""
+Utility functions for PyScript.
+
+This module contains general-purpose utility functions that don't fit into
+more specific modules. These utilities handle cross-platform compatibility
+between Pyodide and MicroPython, feature detection, and common type
+conversions:
+
+- `as_bytearray`: Convert JavaScript `ArrayBuffer` to Python `bytearray`.
+- `NotSupported`: Placeholder for unavailable features in specific contexts.
+- `is_awaitable`: Detect `async` functions across Python implementations.
+
+These utilities are primarily used internally by PyScript but are available
+for use in application code when needed.
+"""
+
+import js
+import inspect
+
+
+def as_bytearray(buffer):
+    """
+    Given a JavaScript ArrayBuffer, convert it to a Python bytearray in a
+    MicroPython friendly manner.
+    """
+    ui8a = js.Uint8Array.new(buffer)
+    size = ui8a.length
+    ba = bytearray(size)
+    for i in range(size):
+        ba[i] = ui8a[i]
+    return ba
+
+
+class NotSupported:
+    """
+    Small helper that raises exceptions if you try to get/set any attribute on
+    it.
+    """
+
+    def __init__(self, name, error):
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "error", error)
+
+    def __repr__(self):
+        return f"<NotSupported {self.name} [{self.error}]>"
+
+    def __getattr__(self, attr):
+        raise AttributeError(self.error)
+
+    def __setattr__(self, attr, value):
+        raise AttributeError(self.error)
+
+    def __call__(self, *args):
+        raise TypeError(self.error)
+
+
+def is_awaitable(obj):
+    """
+    Returns a boolean indication if the passed in obj is an awaitable
+    function. (MicroPython treats awaitables as generator functions, and if
+    the object is a closure containing an async function we need to work
+    carefully.)
+    """
+    from pyscript import config
+
+    if config["type"] == "mpy":  # Is MicroPython?
+        # MicroPython doesn't appear to have a way to determine if a closure is
+        # an async function except via the repr. This is a bit hacky.
+        r = repr(obj)
+        if "<closure <generator>" in r:
+            return True
+        # Same applies to bound methods.
+        if "<bound_method" in r and "<generator>" in r:
+            return True
+        return inspect.isgeneratorfunction(obj)
+
+    return inspect.iscoroutinefunction(obj)
diff --git a/pyscript/web.py b/pyscript/web.py
new file mode 100644
index 0000000..43d8bd4
--- /dev/null
+++ b/pyscript/web.py
@@ -0,0 +1,1410 @@
+"""
+A lightweight Pythonic interface to the DOM and HTML elements that helps you
+to interact with web pages, making it easy to find, create, manipulate, and
+compose HTML elements from Python.
+
+Use the `page` object to find elements on the current page:
+
+```python
+from pyscript import web
+
+# Find by CSS selector (returns an ElementCollection).
+divs = web.page.find("div")
+buttons = web.page.find(".button-class")
+
+# Get element by ID (returns single Element or None).
+header = web.page["header-id"]
+header = web.page["#header-id"]  # the "#" prefix is optional.
+
+# Access page structure.
+web.page.body.append(some_element)
+web.page.title = "New Page Title"
+```
+
+Create new elements and compose them together:
+
+```python
+# Create simple elements.
+div = web.div("Hello, World!")
+paragraph = web.p("Some text", id="my-para", className="text-content")
+
+# Compose elements together.
+container = web.div(
+    web.h1("Title"),
+    web.p("First paragraph"),
+    web.p("Second paragraph"),
+    id="container"
+)
+
+# Add to the page.
+web.page.body.append(container)
+
+# Create with initial attributes.
+link = web.a(
+    "Click me",
+    href="https://example.com",
+    target="_blank",
+    classes=["link", "external"]
+)
+```
+
+Modify element content and attributes:
+
+```python
+# Update content.
+element.innerHTML = "<b>Bold text</b>"
+element.textContent = "Plain text"
+
+# Update attributes.
+element.id = "new-id"
+element.title = "Tooltip text"
+
+# Bulk update with convenience method.
+element.update(
+    classes=["active", "highlighted"],
+    style={"color": "red", "font-size": "16px"},
+    title="Updated tooltip"
+)
+```
+
+An element's CSS classes behave like Python sets:
+
+```python
+# Add and remove classes
+element.classes.add("active")
+element.classes.add("highlighted")
+element.classes.remove("hidden")
+
+# Check membership.
+if "active" in element.classes:
+    print("Element is active")
+
+# Clear all classes.
+element.classes.clear()
+
+# Discard (no error if missing).
+element.classes.discard("maybe-not-there")
+```
+
+An element's styles behave like Python dictionaries:
+
+```python
+# Set individual styles.
+element.style["color"] = "red"
+element.style["background-color"] = "#f0f0f0"
+element.style["font-size"] = "16px"
+
+# Remove a style.
+del element.style["margin"]
+
+# Check if style is set.
+if "color" in element.style:
+    print(f"Color is {element.style['color']}")
+```
+
+Update multiple elements at once via an ElementCollection:
+
+```python
+# Find multiple elements (returns an ElementCollection).
+items = web.page.find(".list-item")
+
+# Iterate over collection.
+for item in items:
+    item.innerHTML = "Updated"
+    item.classes.add("processed")
+
+# Bulk update all elements.
+items.update_all(
+    innerHTML="Hello",
+    className="updated-item"
+)
+
+# Index and slice collections.
+first = items[0]
+subset = items[1:3]
+
+# Get an element by ID within the collection.
+special = items["special-id"]
+
+# Find descendants within the collection.
+subitems = items.find(".sub-item")
+```
+
+Manage `select` element options (also for `datalist` and `optgroup`):
+
+```python
+# Get existing select.
+select = web.page["my-select"]
+
+# Add options.
+select.options.add(value="1", html="Option 1")
+select.options.add(value="2", html="Option 2", selected=True)
+
+# Get selected option.
+selected = select.options.selected
+print(f"Selected: {selected.value}")
+
+# Iterate over options.
+for option in select.options:
+    print(f"{option.value}: {option.innerHTML}")
+
+# Clear all options.
+select.options.clear()
+
+# Remove specific option by index.
+select.options.remove(0)
+```
+
+Attach event handlers to elements:
+
+```python
+from pyscript import when
+
+button = web.button("Click me", id="my-button")
+
+# Use the when decorator.
+@when("click", button)
+def handle_click(event):
+    print("Button clicked!")
+
+# Or add directly to the event.
+def another_handler(event):
+    print("Another handler")
+
+button.on_click.add_listener(another_handler)
+
+# Pass handler during creation.
+button = web.button("Click", on_click=handle_click)
+```
+
+All Element instances provide direct access to the underlying DOM element
+via attribute delegation:
+
+```python
+# Most DOM methods are accessible directly.
+element.scrollIntoView()
+element.focus()
+element.blur()
+
+# But we do have a convenience method for scrolling into view.
+element.show_me()  # Calls scrollIntoView()
+
+# Access the raw DOM element when needed for special cases.
+dom_element = element._dom_element
+```
+
+The main entry point is the `page` object, which represents the current
+document and provides access to common elements like `page.body` and methods
+like `page.find()` for querying the DOM.
+"""
+
+from pyscript import document, when, Event  # noqa: F401
+from pyscript.ffi import create_proxy, is_none
+
+
+# Utility functions for finding and wrapping DOM elements.
+
+
+def _wrap_if_not_none(dom_element):
+    """
+    Wrap a `dom_element`, returning `None` if the element is `None`/`null`.
+    """
+    return Element.wrap_dom_element(dom_element) if not is_none(dom_element) else None
+
+
+def _find_by_id(dom_node, target_id):
+    """
+    Find an element by `id` within a `dom_node`.
+
+    The `target_id` can optionally start with '#'. Returns a wrapped `Element`
+    or `None` if not found.
+    """
+    element_id = target_id[1:] if target_id.startswith("#") else target_id
+    result = dom_node.querySelector(f"#{element_id}")
+    return _wrap_if_not_none(result)
+
+
+def _find_and_wrap(dom_node, selector):
+    """
+    Find all descendants of `dom_node` matching the CSS `selector`.
+
+    Returns an `ElementCollection` of wrapped elements.
+    """
+    return ElementCollection.wrap_dom_elements(dom_node.querySelectorAll(selector))
+
+
+class Element:
+    """
+    The base class for all HTML elements.
+
+    Provides a Pythonic interface to DOM elements with support for attributes,
+    events, styles, classes, and DOM manipulation. It can create new elements
+    or wrap existing DOM elements.
+
+    Elements are typically created using the tag-specific classes:
+
+    ```python
+    from pyscript import web
+
+
+    # Create a simple div.
+    div = web.div("Hello, World!")
+
+    # Create with attributes.
+    link = web.a("Click me", href="https://example.com", target="_blank")
+
+    # Create with classes and styles.
+    button = web.button(
+        "Submit",
+        classes=["primary", "large"],
+        style={"background-color": "blue", "color": "white"},
+        id="submit-btn"
+    )
+    ```
+
+    Wrap existing DOM elements found on the page:
+
+    ```python
+    # Find and wrap an element.
+    existing = web.page.find("#my-element")[0]
+
+    # Or, better, just use direct ID lookup.
+    existing = web.page["my-element"]
+    ```
+
+    Element attributes are accessible as Python properties:
+
+    ```python
+    # Get attributes.
+    element_id = div.id
+    element_title = div.title
+    element_href = link.href
+
+    # Set attributes.
+    div.id = "new-id"
+    div.title = "Tooltip text"
+    link.href = "https://new-url.com"
+
+    # HTML content.
+    div.innerHTML = "<b>Bold text</b>"
+    div.textContent = "Plain text"
+    ```
+
+    CSS classes are managed through a set-like interface:
+
+    ```python
+    # Add classes.
+    element.classes.add("active")
+    element.classes.add("highlighted")
+
+    # Remove classes.
+    element.classes.remove("inactive")
+    element.classes.discard("maybe-missing")  # No error if absent
+
+    # Check membership.
+    if "active" in element.classes:
+        print("Element is active")
+
+    # Iterate over classes.
+    for cls in element.classes:
+        print(cls)
+    ```
+
+    Explicit CSS styles are managed through a dict-like interface:
+
+    ```python
+    # Set styles using CSS property names (hyphenated).
+    element.style["color"] = "red"
+    element.style["background-color"] = "#f0f0f0"
+    element.style["font-size"] = "16px"
+
+    # Get styles.
+    color = element.style["color"]
+
+    # Remove styles.
+    del element.style["margin"]
+    ```
+
+    Add, find, and navigate elements:
+
+    ```python
+    # Append children.
+    parent.append(child_element)
+    parent.append(child1, child2, child3)  # Multiple at once
+
+    # Find descendants using CSS selectors.
+    buttons = parent.find("button")
+    items = parent.find(".item-class")
+
+    # Navigate the tree.
+    child = parent.children[0]
+    parent_elem = child.parent
+
+    # Access children by index or slice.
+    first_child = parent[0]
+    first_three = parent[0:3]
+
+    # Get a child explicitly by ID. Returns None if not found.
+    specific = parent["child-id"]
+    ```
+
+    Attach event listeners to elements:
+
+    ```python
+    button = web.button("Click me")
+
+    # Use the @when decorator with event name.
+    from pyscript import when
+
+    @when("click", button)
+    def handle_click(event):
+        print("Clicked!")
+
+    # Or use the on_* event directly with @when.
+    @when(button.on_click)
+    def handle_click(event):
+        print("Also works!")
+
+    # Pass handlers during element creation.
+    button = web.button("Click", on_click=handle_click)
+    ```
+
+    Update multiple properties at once:
+
+    ```python
+    element.update(
+        classes=["active", "highlighted"],
+        style={"color": "red", "font-size": "20px"},
+        id="updated-id",
+        title="New tooltip"
+    )
+    ```
+
+    **Some HTML attributes clash with Python keywords and use trailing
+    underscores**:
+
+    ```python
+    # The 'for' attribute (on labels)
+    label = web.label("Username", for_="username-input")
+
+    # The 'class' attribute (though 'classes' is preferred)
+    div.class_ = "my-class"
+    ```
+
+    Create copies of elements:
+
+    ```python
+    original = web.div("Original content", id="original")
+    clone = original.clone(clone_id="cloned")
+    ```
+
+    Access the underlying DOM element when needed:
+
+    ```python
+    # Most DOM properties and methods are accessible directly.
+    element.focus()
+    element.scrollIntoView()
+    bounding_rect = element.getBoundingClientRect()
+
+    # Or access the raw DOM element.
+    dom_element = element._dom_element
+    ```
+    """
+
+    # Lookup table: tag name -> Element subclass.
+    element_classes_by_tag_name = {}
+
+    @classmethod
+    def get_tag_name(cls):
+        """
+        Get the HTML tag name for this class.
+
+        Classes ending with underscore (e.g. `input_`) have it removed to get
+        the actual HTML tag name.
+        """
+        return cls.__name__.replace("_", "")
+
+    @classmethod
+    def register_element_classes(cls, element_classes):
+        """
+        Register `Element` subclasses for tag-based lookup.
+        """
+        for element_class in element_classes:
+            tag_name = element_class.get_tag_name()
+            cls.element_classes_by_tag_name[tag_name] = element_class
+
+    @classmethod
+    def unregister_element_classes(cls, element_classes):
+        """
+        Unregister `Element` subclasses from tag-based lookup.
+        """
+        for element_class in element_classes:
+            tag_name = element_class.get_tag_name()
+            cls.element_classes_by_tag_name.pop(tag_name, None)
+
+    @classmethod
+    def wrap_dom_element(cls, dom_element):
+        """
+        Wrap a DOM element in the appropriate `Element` subclass.
+
+        Looks up the subclass by tag name. Unknown tags use the base `Element`
+        class.
+        """
+        element_cls = cls.element_classes_by_tag_name.get(
+            dom_element.tagName.lower(), cls
+        )
+        return element_cls(dom_element=dom_element)
+
+    def __init__(self, dom_element=None, classes=None, style=None, **kwargs):
+        """
+        Create or wrap a DOM element.
+
+        If `dom_element` is `None`, this creates a new element. Otherwise wraps
+        the provided DOM element. The `**kwargs` can include HTML attributes
+        and event handlers (names starting with `on_`).
+        """
+        # Create or wrap the DOM element.
+        if is_none(dom_element):
+            self._dom_element = document.createElement(type(self).get_tag_name())
+        else:
+            self._dom_element = dom_element
+        # Event handling.
+        self._on_events = {}
+        self.update(classes=classes, style=style, **kwargs)
+
+    def __eq__(self, obj):
+        """
+        Check equality by comparing underlying DOM elements.
+        """
+        return isinstance(obj, Element) and obj._dom_element == self._dom_element
+
+    def __getitem__(self, key):
+        """
+        Get an item within this element.
+
+        Behaviour depends on the key type:
+
+        - Integer: returns the child at that index.
+        - Slice: returns a collection of children in that slice.
+        - String: looks up an element by id (with or without '#' prefix).
+
+        ```python
+        element[0]          # First child.
+        element[1:3]        # Second and third children.
+        element["my-id"]    # Element with id="my-id" (or None).
+        element["#my-id"]   # Same as above (# is optional).
+        ```
+        """
+
+        if isinstance(key, (int, slice)):
+            return self.children[key]
+        if isinstance(key, str):
+            return _find_by_id(self._dom_element, key)
+        raise TypeError(
+            f"Element indices must be integers, slices, or strings, "
+            f"not {type(key).__name__}."
+        )
+
+    def __getattr__(self, name):
+        """
+        Get an attribute from the element.
+
+        Attributes starting with `on_` return `Event` instances. Other
+        attributes are retrieved from the underlying DOM element.
+        """
+        if name.startswith("on_"):
+            return self.get_event(name)
+        dom_name = self._normalize_attribute_name(name)
+        return getattr(self._dom_element, dom_name)
+
+    def __setattr__(self, name, value):
+        """
+        Set an attribute on the element.
+
+        Private attributes (starting with `_`) are set on the Python object.
+        Public attributes are set on the underlying DOM element.
+        """
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+        elif name.startswith("on_"):
+            # Separate events...
+            self.get_event(name).add_listener(value)
+        else:
+            # ...from regular attributes.
+            dom_name = self._normalize_attribute_name(name)
+            setattr(self._dom_element, dom_name, value)
+
+    def _normalize_attribute_name(self, name):
+        """
+        Normalize Python attribute names to DOM attribute names.
+
+        Removes trailing underscores and maps special cases.
+        """
+        if name.endswith("_"):
+            name = name[:-1]
+        if name == "for":
+            return "htmlFor"
+        if name == "class":
+            return "className"
+        return name
+
+    def get_event(self, name):
+        """
+        Get an `Event` instance for the specified event name.
+
+        Event names must start with `on_` (e.g. `on_click`). Creates and
+        caches `Event` instances that are triggered when the DOM event fires.
+        """
+        if not name.startswith("on_"):
+            raise ValueError("Event names must start with 'on_'.")
+        event_name = name[3:]  # Remove 'on_' prefix.
+        if not hasattr(self._dom_element, event_name):
+            raise ValueError(f"Element has no '{event_name}' event.")
+        if name in self._on_events:
+            return self._on_events[name]
+        # Create Event instance and wire it to the DOM event.
+        ev = Event()
+        self._on_events[name] = ev
+        self._dom_element.addEventListener(event_name, create_proxy(ev.trigger))
+        return ev
+
+    @property
+    def children(self):
+        """
+        Return this element's children as an `ElementCollection`.
+        """
+        return ElementCollection.wrap_dom_elements(self._dom_element.children)
+
+    @property
+    def classes(self):
+        """
+        Return the element's CSS classes as a set-like object.
+
+        Supports set operations: `add`, `remove`, `discard`, `clear`.
+        Check membership with `in`, iterate with `for`, get length with `len()`.
+
+        ```python
+        element.classes.add("active")
+        if "disabled" in element.classes:
+            ...
+        ```
+        """
+        if not hasattr(self, "_classes"):
+            self._classes = Classes(self)
+        return self._classes
+
+    @property
+    def style(self):
+        """
+        Return the element's CSS styles as a dict-like object.
+
+        Access using dict-style syntax with CSS property names (hyphenated).
+
+        ```python
+        element.style["background-color"] = "red"
+        element.style["font-size"] = "16px"
+        del element.style["margin"]
+        ```
+        """
+        if not hasattr(self, "_style"):
+            self._style = Style(self)
+        return self._style
+
+    @property
+    def parent(self):
+        """
+        Return this element's parent `Element`, or `None`.
+        """
+        if is_none(self._dom_element.parentElement):
+            return None
+        return Element.wrap_dom_element(self._dom_element.parentElement)
+
+    def append(self, *items):
+        """
+        Append items to this element's `children`.
+
+        Accepts `Element` instances, `ElementCollection` instances, lists,
+        tuples, raw DOM elements, and NodeLists.
+        """
+        for item in items:
+            if isinstance(item, Element):
+                self._dom_element.appendChild(item._dom_element)
+            elif isinstance(item, ElementCollection):
+                for element in item:
+                    self._dom_element.appendChild(element._dom_element)
+            elif isinstance(item, (list, tuple)):
+                for child in item:
+                    self.append(child)
+            elif hasattr(item, "tagName"):
+                # Raw DOM element.
+                self._dom_element.appendChild(item)
+            elif hasattr(item, "length"):
+                # NodeList or similar iterable.
+                for element in item:
+                    self._dom_element.appendChild(element)
+            else:
+                raise TypeError(f"Cannot append {type(item).__name__} to element.")
+
+    def clone(self, clone_id=None):
+        """
+        Clone this element and its underlying DOM element.
+
+        Optionally assign a new `id` to the clone.
+        """
+        clone = Element.wrap_dom_element(self._dom_element.cloneNode(True))
+        clone.id = clone_id
+        return clone
+
+    def find(self, selector):
+        """
+        Find all descendant elements matching the CSS selector.
+
+        Returns an `ElementCollection` (possibly empty).
+
+        ```python
+        element.find("div")              # All div descendants.
+        element.find(".my-class")        # All elements with class.
+        element.find("#my-id")           # Element with id (as collection).
+        element.find("div.my-class")     # All divs with class.
+        ```
+        """
+        return _find_and_wrap(self._dom_element, selector)
+
+    def show_me(self):
+        """
+        Scroll this element into view.
+        """
+        self._dom_element.scrollIntoView()
+
+    def update(self, classes=None, style=None, **kwargs):
+        """
+        Update this element's `classes`, `style`, and `attributes`
+        (via arbitrary `**kwargs`).
+
+        Convenience method for bulk updates.
+        """
+        if classes:
+            if isinstance(classes, str):
+                self.classes.add(classes)
+            else:
+                for class_name in classes:
+                    self.classes.add(class_name)
+        if style:
+            for key, value in style.items():
+                self.style[key] = value
+        for name, value in kwargs.items():
+            setattr(self, name, value)
+
+
+class Classes(set):
+    """
+    A set of CSS class names that syncs with the DOM.
+
+    Behaves like a Python set with changes automatically reflected in the
+    element's classList.
+
+    ```python
+    # Add and remove classes.
+    element.classes.add("active")
+    element.classes.remove("inactive")
+    element.classes.discard("maybe-missing")  # No error if absent.
+
+    # Check membership.
+    if "active" in element.classes:
+        print("Element is active")
+
+    # Clear all classes.
+    element.classes.clear()
+
+    # Iterate over classes.
+    for cls in element.classes:
+        print(cls)
+    ```
+    """
+
+    def __init__(self, element):
+        self._class_list = element._dom_element.classList
+        super().__init__(self._class_list)
+
+    def _extract_class_names(self, class_name):
+        """
+        If the class_name contains several class names separated by spaces,
+        split them and return as a list. Otherwise, return the class_name as is
+        in a list.
+        """
+        return (
+            [name for name in class_name.split() if name]
+            if " " in class_name
+            else [class_name]
+        )
+
+    def add(self, class_name):
+        """Add a class."""
+        for name in self._extract_class_names(class_name):
+            super().add(name)
+            self._class_list.add(name)
+
+    def remove(self, class_name):
+        """Remove a class."""
+        for name in self._extract_class_names(class_name):
+            super().remove(name)
+            self._class_list.remove(name)
+
+    def discard(self, class_name):
+        """Remove a class if present."""
+        for name in self._extract_class_names(class_name):
+            super().discard(name)
+            if name in self._class_list:
+                self._class_list.remove(name)
+
+    def clear(self):
+        """Remove all classes."""
+        super().clear()
+        while self._class_list.length > 0:
+            self._class_list.remove(self._class_list.item(0))
+
+
+class Style(dict):
+    """
+    A dictionary of CSS styles that syncs with the DOM.
+
+    Behaves like a Python dict with changes automatically reflected in the
+    element's style attribute.
+
+    ```python
+    # Set and get styles using CSS property names (hyphenated).
+    element.style["color"] = "red"
+    element.style["background-color"] = "#f0f0f0"
+    element.style["font-size"] = "16px"
+
+    # Get a style value.
+    color = element.style["color"]
+
+    # Remove a style.
+    del element.style["margin"]
+
+    # Check if a style is set.
+    if "color" in element.style:
+        print(f"Color is {element.style['color']}")
+    ```
+    """
+
+    def __init__(self, element):
+        self._style = element._dom_element.style
+        super().__init__()
+
+    def __setitem__(self, key, value):
+        """Set a style property."""
+        super().__setitem__(key, value)
+        self._style.setProperty(key, str(value))
+
+    def __delitem__(self, key):
+        """Remove a style property."""
+        super().__delitem__(key)
+        self._style.removeProperty(key)
+
+
+class HasOptions:
+    """
+    Mixin for elements with options (`datalist`, `optgroup`, `select`).
+
+    Provides an options property that returns an `Options` instance. Used
+    in conjunction with the `Options` class.
+
+    ```python
+    # Get a select element and work with its options.
+    select = web.page["my-select"]
+
+    # Add options.
+    select.options.add(value="1", html="Option 1")
+    select.options.add(value="2", html="Option 2", selected=True)
+
+    # Get the selected option.
+    selected = select.options.selected
+
+    # Iterate over options.
+    for option in select.options:
+        print(f"{option.value}: {option.innerHTML}")
+
+    # Clear all options.
+    select.options.clear()
+    ```
+    """
+
+    @property
+    def options(self):
+        """Return this element's options as an Options instance."""
+        if not hasattr(self, "_options"):
+            self._options = Options(self)
+        return self._options
+
+
+class Options:
+    """
+    Interface to the options of a `datalist`, `optgroup`, or `select` element.
+
+    Supports adding, removing, and accessing option elements. Used in
+    conjunction with the `HasOptions` mixin.
+
+    ```python
+    # Add options to a select element.
+    select.options.add(value="1", html="Option 1")
+    select.options.add(value="2", html="Option 2", selected=True)
+
+    # Insert option at specific position.
+    select.options.add(value="1.5", html="Option 1.5", before=1)
+
+    # Access options by index.
+    first_option = select.options[0]
+
+    # Get the selected option.
+    selected = select.options.selected
+    print(f"Selected: {selected.value}")
+
+    # Iterate over all options.
+    for option in select.options:
+        print(option.innerHTML)
+
+    # Remove option by index.
+    select.options.remove(0)
+
+    # Clear all options.
+    select.options.clear()
+    ```
+    """
+
+    def __init__(self, element):
+        self._element = element
+
+    def __getitem__(self, key):
+        return self.options[key]
+
+    def __iter__(self):
+        yield from self.options
+
+    def __len__(self):
+        return len(self.options)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__} (length: {len(self)}) " f"{self.options}"
+
+    @property
+    def options(self):
+        """
+        Return the list of option elements.
+        """
+        return [Element.wrap_dom_element(o) for o in self._element._dom_element.options]
+
+    @property
+    def selected(self):
+        """
+        Return the currently selected option.
+        """
+        return self.options[self._element._dom_element.selectedIndex]
+
+    def add(self, value=None, html=None, text=None, before=None, **kwargs):
+        """
+        Add a new option to the element.
+
+        Can specify `value`, `html` content, and `text`. The `before` parameter can
+        be an `Element` or index to insert before. The `**kwargs` are additional
+        arbitrary attributes for the new option element.
+        """
+        if value:
+            kwargs["value"] = value
+        if html:
+            kwargs["innerHTML"] = html
+        if text:
+            kwargs["text"] = text
+
+        # The `option` element class is dynamically created below.
+        new_option = option(**kwargs)  # noqa: F821
+
+        if before and isinstance(before, Element):
+            before = before._dom_element
+
+        self._element._dom_element.add(new_option._dom_element, before)
+
+    def clear(self):
+        """
+        Remove all options.
+        """
+        self._element._dom_element.length = 0
+
+    def remove(self, index):
+        """
+        Remove the option at the specified index.
+        """
+        self._element._dom_element.remove(index)
+
+
+class ContainerElement(Element):
+    """
+    Base class for elements that can contain other elements.
+
+    Extends `Element` with convenient child handling during initialization.
+
+    ```python
+    from pyscript import web
+
+
+    # Create with child elements as arguments.
+    div = web.div(
+        web.h1("Title"),
+        web.p("Paragraph 1"),
+        web.p("Paragraph 2")
+    )
+
+    # Or use the children keyword argument.
+    div = web.div(children=[web.p("Child 1"), web.p("Child 2")])
+
+    # Mix elements and HTML strings.
+    div = web.div(
+        web.h1("Title"),
+        "<p>HTML content</p>",
+        web.button("Click me")
+    )
+
+    # Iterate over children.
+    for child in div:
+        print(child.innerHTML)
+    ```
+    """
+
+    def __init__(
+        self, *args, children=None, dom_element=None, style=None, classes=None, **kwargs
+    ):
+        """
+        Create a container element with optional `children`.
+
+        Children can be passed as positional `*args` or via the `children`
+        keyword argument. String children are inserted as HTML. The `style`,
+        `classes`, and `**kwargs` are passed to the base `Element` initializer.
+        """
+        super().__init__(
+            dom_element=dom_element, style=style, classes=classes, **kwargs
+        )
+
+        for child in list(args) + (children or []):
+            if isinstance(child, (Element, ElementCollection)):
+                self.append(child)
+            else:
+                self._dom_element.insertAdjacentHTML("beforeend", child)
+
+    def __iter__(self):
+        yield from self.children
+
+
+class ElementCollection:
+    """
+    A collection of Element instances with list-like operations.
+
+    Supports iteration, indexing, slicing, and finding descendants.
+    For bulk operations, iterate over the collection explicitly or use
+    the `update_all` method.
+
+    ```python
+    # Get a collection of elements.
+    items = web.page.find(".item")
+
+    # Access by index.
+    first = items[0]
+    last = items[-1]
+
+    # Slice the collection.
+    subset = items[1:3]
+
+    # Look up a specific element by id (returns None if not found).
+    specific = items["item-id"]
+
+    # Iterate over elements.
+    for item in items:
+        item.innerHTML = "Updated"
+        item.classes.add("processed")
+
+    # Bulk update all elements.
+    items.update_all(innerHTML="Hello", className="updated")
+
+    # Find matches within the collection.
+    buttons = items.find("button")
+
+    # Get the count.
+    count = len(items)
+    ```
+    """
+
+    @classmethod
+    def wrap_dom_elements(cls, dom_elements):
+        """
+        Wrap an iterable of DOM elements in an ElementCollection.
+        """
+        return cls(
+            [Element.wrap_dom_element(dom_element) for dom_element in dom_elements]
+        )
+
+    def __init__(self, elements):
+        self._elements = elements
+
+    def __eq__(self, obj):
+        """
+        Check equality by comparing elements.
+        """
+        return isinstance(obj, ElementCollection) and obj._elements == self._elements
+
+    def __getitem__(self, key):
+        """
+        Get items from the collection.
+
+        Behaviour depends on the key type:
+
+        - Integer: returns the element at that index.
+        - Slice: returns a new collection with elements in that slice.
+        - String: looks up an element by id (with or without '#' prefix).
+
+        ```python
+        collection[0]          # First element.
+        collection[1:3]        # New collection with 2nd and 3rd elements.
+        collection["my-id"]    # Element with id="my-id" (or None).
+        collection["#my-id"]   # Same as above (# is optional).
+        ```
+        """
+        if isinstance(key, int):
+            return self._elements[key]
+        if isinstance(key, slice):
+            return ElementCollection(self._elements[key])
+        if isinstance(key, str):
+            for element in self._elements:
+                result = _find_by_id(element._dom_element, key)
+                if result:
+                    return result
+            return None
+        raise TypeError(
+            f"Collection indices must be integers, slices, or strings, "
+            f"not {type(key).__name__}"
+        )
+
+    def __iter__(self):
+        yield from self._elements
+
+    def __len__(self):
+        return len(self._elements)
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__} (length: {len(self._elements)}) "
+            f"{self._elements}"
+        )
+
+    @property
+    def elements(self):
+        """
+        Return the underlying list of elements.
+        """
+        return self._elements
+
+    def find(self, selector):
+        """
+        Find all descendants matching the CSS selector.
+
+        Searches within all elements in the collection.
+
+        ```python
+        collection.find("div")           # All div descendants.
+        collection.find(".my-class")     # All elements with class.
+        collection.find("#my-id")        # Element with id (as collection).
+        ```
+        """
+        elements = []
+        for element in self._elements:
+            elements.extend(_find_and_wrap(element._dom_element, selector))
+        return ElementCollection(elements)
+
+    def update_all(self, **kwargs):
+        """
+        Explicitly update all elements with the given attributes.
+
+        ```python
+        collection.update_all(innerHTML="Hello")
+        collection.update_all(className="active", title="Updated")
+        ```
+        """
+        for element in self._elements:
+            for name, value in kwargs.items():
+                setattr(element, name, value)
+
+
+# Special elements with custom methods and mixins.
+
+
+class canvas(ContainerElement):
+    """
+    HTML canvas element with drawing and download capabilities.
+
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas
+    """
+
+    def download(self, filename="snapped.png"):
+        """
+        Download the canvas content as an image file.
+
+        Creates a temporary download link and triggers it.
+        """
+        # The `a` element class is dynamically created below.
+        download_link = a(  # noqa: F821
+            download=filename, href=self._dom_element.toDataURL()
+        )
+        self.append(download_link)
+        download_link._dom_element.click()
+
+    def draw(self, what, width=None, height=None):
+        """
+        Draw a 2d image source (`what`) onto the canvas. Optionally scale to
+        `width` and `height`.
+
+        Accepts canvas image sources: `HTMLImageElement`, `SVGImageElement`,
+        `HTMLVideoElement`, `HTMLCanvasElement`, `ImageBitmap`,
+        `OffscreenCanvas`, or `VideoFrame`.
+        """
+        if isinstance(what, Element):
+            what = what._dom_element
+
+        ctx = self._dom_element.getContext("2d")
+        if width or height:
+            ctx.drawImage(what, 0, 0, width, height)
+        else:
+            ctx.drawImage(what, 0, 0)
+
+
+class video(ContainerElement):
+    """
+    HTML video element with snapshot capability.
+
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
+    """
+
+    def snap(self, to=None, width=None, height=None):
+        """
+        Capture a video frame `to` a canvas element. Optionally scale to
+        `width` and `height`.
+
+        If no canvas is provided, this will create one. The to parameter
+        can be a canvas Element, raw DOM canvas, or CSS selector string.
+        """
+        width = width if width else self.videoWidth
+        height = height if height else self.videoHeight
+        if is_none(to):
+            to = canvas(width=width, height=height)
+        elif isinstance(to, Element):
+            if to.tag != "canvas":
+                raise TypeError("Element to snap to must be a canvas.")
+        elif getattr(to, "tagName", "") == "CANVAS":
+            to = canvas(dom_element=to)
+        elif isinstance(to, str):
+            nodelist = document.querySelectorAll(to)
+            if nodelist.length == 0:
+                raise TypeError(f"No element with selector {to} to snap to.")
+            if nodelist[0].tagName != "CANVAS":
+                raise TypeError("Element to snap to must be a canvas.")
+            to = canvas(dom_element=nodelist[0])
+        to.draw(self, width, height)
+        return to
+
+
+class datalist(ContainerElement, HasOptions):
+    """
+    HTML datalist element with options support.
+
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
+    """
+
+
+class optgroup(ContainerElement, HasOptions):
+    """
+    HTML optgroup element with options support.
+
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup
+    """
+
+
+class select(ContainerElement, HasOptions):
+    """
+    HTML select element with options support.
+
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select
+    """
+
+
+# Container elements that can have children.
+# Note: canvas, video, datalist, optgroup, and select are defined above
+# with special implementations due to the HasOptions mixin.
+# fmt: off
+CONTAINER_TAGS = [
+    "a", "abbr", "address", "article", "aside", "audio",
+    "b", "blockquote", "body", "button",
+    "caption", "cite", "code", "colgroup",
+    "data", "dd", "del", "details", "dialog", "div", "dl", "dt",
+    "em",
+    "fieldset", "figcaption", "figure", "footer", "form",
+    "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup", "html",
+    "i", "iframe", "ins",
+    "kbd",
+    "label", "legend", "li",
+    "main", "map", "mark", "menu", "meta", "meter",
+    "nav",
+    "object", "ol", "option", "output",
+    "p", "param", "picture", "pre", "progress",
+    "q",
+    "s", "script", "section", "small", "span", "strong", "style",
+    "sub", "summary", "sup",
+    "table", "tbody", "td", "template", "textarea", "tfoot", "th", "thead",
+    "time", "title", "tr",
+    "u", "ul",
+    "var",
+    "wbr",
+]
+# fmt: on
+
+# Void elements that cannot have children.
+VOID_TAGS = [
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "source",
+    "track",
+]
+
+
+def _create_element_classes():
+    """
+    Create element classes dynamically and register them.
+
+    Generates classes for all standard HTML elements, using the appropriate
+    base class (ContainerElement or Element) for each tag.
+    """
+    # The existing special element classes defined above.
+    classes = [canvas, video, datalist, optgroup, select]
+    for tag in CONTAINER_TAGS:
+        # Tags that clash with Python keywords get a trailing underscore.
+        class_name = f"{tag}_" if tag in ("del", "map", "object") else tag
+        doc = (
+            f"HTML <{tag}> element. "
+            f"Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/"
+            f"Element/{tag}"
+        )
+        cls = type(class_name, (ContainerElement,), {"__doc__": doc})
+        globals()[class_name] = cls
+        classes.append(cls)
+    for tag in VOID_TAGS:
+        class_name = f"{tag}_" if tag == "input" else tag
+        doc = (
+            f"HTML <{tag}> element. "
+            f"Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/"
+            f"Element/{tag}"
+        )
+        cls = type(class_name, (Element,), {"__doc__": doc})
+        globals()[class_name] = cls
+        classes.append(cls)
+    Element.register_element_classes(classes)
+
+
+# Initialize element classes at module load time. :-)
+_create_element_classes()
+
+
+class Page:
+    """
+    Represents the current web page.
+
+    Provides access to the document's html, head, and body elements, plus
+    convenience methods for finding elements and appending to the body.
+
+    ```python
+    from pyscript import web
+
+
+    # Access page structure.
+    web.page.html  # The <html> element.
+    web.page.head  # The <head> element.
+    web.page.body  # The <body> element.
+
+    # Get and set page title.
+    web.page.title = "New Title"
+    print(web.page.title)
+
+    # Find elements by CSS selector.
+    divs = web.page.find("div")
+    items = web.page.find(".item-class")
+
+    # Look up element by id.
+    element = web.page["my-id"]
+    element = web.page["#my-id"]  # The "#" prefix is optional.
+
+    # Append to the body (shortcut for page.body.append).
+    web.page.append(web.div("Hello"))
+    ```
+    """
+
+    def __init__(self):
+        self.html = Element.wrap_dom_element(document.documentElement)
+        self.body = Element.wrap_dom_element(document.body)
+        self.head = Element.wrap_dom_element(document.head)
+
+    def __getitem__(self, key):
+        """
+        Look up an element by id.
+
+        The '#' prefix is optional and will be stripped if present.
+        Returns None if no element with that id exists.
+
+        ```python
+        page["my-id"]      # Element with id="my-id" (or None)
+        page["#my-id"]     # Same as above (# is optional)
+        ```
+        """
+        return _find_by_id(document, key)
+
+    @property
+    def title(self):
+        """
+        Get the page title.
+        """
+        return document.title
+
+    @title.setter
+    def title(self, value):
+        """
+        Set the page title.
+        """
+        document.title = value
+
+    def append(self, *items):
+        """
+        Append items to the page body.
+
+        Shortcut for `page.body.append(*items)`.
+        """
+        self.body.append(*items)
+
+    def find(self, selector):
+        """
+        Find all elements matching the CSS selector.
+
+        Returns an `ElementCollection` of matching elements.
+
+        ```python
+        page.find("div")              # All divs on the page
+        page.find(".my-class")        # All elements with class
+        page.find("#my-id")           # Element with id (as collection)
+        page.find("div.my-class")     # All divs with class
+        ```
+        """
+        return _find_and_wrap(document, selector)
+
+
+page = Page()
diff --git a/pyscript/websocket.py b/pyscript/websocket.py
new file mode 100644
index 0000000..5d9874c
--- /dev/null
+++ b/pyscript/websocket.py
@@ -0,0 +1,298 @@
+"""
+WebSocket support for PyScript.
+
+This module provides a Pythonic wrapper around the browser's WebSocket API,
+enabling two-way communication with WebSocket servers.
+
+Use this for real-time applications:
+
+- Pythonic interface to browser WebSockets.
+- Automatic handling of async event handlers.
+- Support for receiving text (`str`) and binary (`memoryview`) data.
+- Support for sending text (`str`) and binary (`bytes` and `bytearray`) data.
+- Compatible with Pyodide and MicroPython.
+- Works in webworker contexts.
+- Naming deliberately follows the JavaScript WebSocket API closely for
+  familiarity.
+
+See the Python docs for an explanation of memoryview:
+
+https://docs.python.org/3/library/stdtypes.html#memoryview
+
+```python
+from pyscript import WebSocket
+
+
+def on_open(event):
+    print("Connected!")
+    ws.send("Hello server")
+
+def on_message(event):
+    print(f"Received: {event.data}")
+
+def on_close(event):
+    print("Connection closed")
+
+ws = WebSocket(url="ws://localhost:8080/")
+ws.onopen = on_open
+ws.onmessage = on_message
+ws.onclose = on_close
+```
+
+For more information about the underlying WebSocket API, see:
+https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+"""
+
+import js
+from pyscript.ffi import create_proxy
+from pyscript.util import as_bytearray, is_awaitable
+
+
+def _attach_event_handler(websocket, handler_name, handler_function):
+    """
+    Given a `websocket`, and `handler_name`, attach the `handler_function`
+    to the `WebSocket` instance, handling both synchronous and asynchronous
+    handler functions.
+
+    Creates a JavaScript proxy for the handler and wraps async handlers
+    appropriately. Handles the `WebSocketEvent` wrapping for all handlers.
+    """
+    if is_awaitable(handler_function):
+
+        async def async_wrapper(event):
+            await handler_function(WebSocketEvent(event))
+
+        wrapped_handler = create_proxy(async_wrapper)
+    else:
+        wrapped_handler = create_proxy(
+            lambda event: handler_function(WebSocketEvent(event))
+        )
+    # Note: Direct assignment (websocket[handler_name]) fails in Pyodide.
+    setattr(websocket, handler_name, wrapped_handler)
+
+
+class WebSocketEvent:
+    """
+    A read-only wrapper for WebSocket event objects.
+
+    This class wraps browser WebSocket events and provides convenient access
+    to event properties. It handles the conversion of binary data from
+    JavaScript typed arrays to Python bytes-like objects.
+
+    The most commonly used property is `event.data`, which contains the
+    message data for "message" events.
+
+    ```python
+    def on_message(event):  # The event is a WebSocketEvent instance.
+        # For text messages.
+        if isinstance(event.data, str):
+            print(f"Text: {event.data}")
+        else:
+            # For binary messages.
+            print(f"Binary: {len(event.data)} bytes")
+    ```
+    """
+
+    def __init__(self, event):
+        """
+        Create a WebSocketEvent wrapper from an underlying JavaScript
+        `event`.
+        """
+        self._event = event
+
+    def __getattr__(self, attr):
+        """
+        Get an attribute `attr` from the underlying event object.
+
+        Handles special conversion of binary data from JavaScript typed
+        arrays to Python memoryview objects.
+        """
+        value = getattr(self._event, attr)
+        if attr == "data" and not isinstance(value, str):
+            if hasattr(value, "to_py"):
+                # Pyodide - convert JavaScript typed array to Python.
+                return value.to_py()
+            else:
+                # MicroPython - manually convert JS ArrayBuffer.
+                return memoryview(as_bytearray(value))
+        return value
+
+
+class WebSocket:
+    """
+    This class provides a Python-friendly interface to WebSocket connections,
+    handling communication with WebSocket servers. It supports both text and
+    binary data transmission.
+
+    It's possible to access the underlying WebSocket methods and properties
+    directly if needed. However, the wrapper provides a more Pythonic API.
+
+    If you need to work with the raw JavaScript WebSocket instance, you can
+    access it via the `_js_websocket` attribute.
+
+    Using textual (`str`) data:
+
+    ```python
+    from pyscript import WebSocket
+
+
+    # Create WebSocket with handlers as arguments.
+    def handle_message(event):
+        print(f"Got: {event.data}")
+
+    ws = WebSocket(
+        url="ws://echo.websocket.org/",
+        onmessage=handle_message
+    )
+
+    # Or assign handlers after creation.
+    def handle_open(event):
+        ws.send("Hello!")
+
+    ws.onopen = handle_open
+    ```
+
+    Using binary (`memoryview`) data:
+
+    ```python
+    def handle_message(event):
+        if isinstance(event.data, str):
+            print(f"Text: {event.data}")
+        else:
+            # Binary data as memoryview.
+            print(f"Binary: {len(event.data)} bytes")
+
+    ws = WebSocket(url="ws://example.com/", onmessage=handle_message)
+
+    # Send binary data.
+    data = bytearray([0x01, 0x02, 0x03])
+    ws.send(data)
+    ```
+
+    See: https://docs.python.org/3/library/stdtypes.html#memoryview
+    """
+
+    # WebSocket ready state constants.
+    CONNECTING = 0
+    OPEN = 1
+    CLOSING = 2
+    CLOSED = 3
+
+    def __init__(self, url, protocols=None, **handlers):
+        """
+        Create a new WebSocket connection from the given `url` (ws:// or
+        wss://). Optionally specify `protocols` (a string or a list of
+        protocol strings) and event handlers (onopen, onmessage, etc.) as
+        keyword arguments.
+
+        These arguments and naming conventions mirror those of the underlying
+        JavaScript WebSocket API for familiarity.
+
+        https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+
+        If you need access to the underlying JavaScript WebSocket instance,
+        you can get it via the `_js_websocket` attribute.
+
+        ```python
+        # Basic connection.
+        ws = WebSocket(url="ws://localhost:8080/")
+
+        # With protocol.
+        ws = WebSocket(
+            url="wss://example.com/socket",
+            protocols="chat"
+        )
+
+        # With handlers.
+        ws = WebSocket(
+            url="ws://localhost:8080/",
+            onopen=lambda e: print("Connected"),
+            onmessage=lambda e: print(e.data)
+        )
+        ```
+        """
+        # Create underlying JavaScript WebSocket.
+        if protocols:
+            js_websocket = js.WebSocket.new(url, protocols)
+        else:
+            js_websocket = js.WebSocket.new(url)
+        # Set binary type to arraybuffer for easier Python handling.
+        js_websocket.binaryType = "arraybuffer"
+        # Store the underlying WebSocket.
+        # Use object.__setattr__ to bypass our custom __setattr__.
+        object.__setattr__(self, "_js_websocket", js_websocket)
+        # Attach any event handlers passed as keyword arguments.
+        for handler_name, handler in handlers.items():
+            setattr(self, handler_name, handler)
+
+    def __getattr__(self, attr):
+        """
+        Get an attribute `attr` from the underlying WebSocket.
+
+        This allows transparent access to WebSocket properties like
+        readyState, url, bufferedAmount, etc.
+        """
+        return getattr(self._js_websocket, attr)
+
+    def __setattr__(self, attr, value):
+        """
+        Set an attribute `attr` on the WebSocket to the given `value`.
+
+        Event handler attributes (onopen, onmessage, etc.) are specially
+        handled to create proper proxies. Other attributes are set on the
+        underlying WebSocket directly.
+        """
+        if attr in ["onclose", "onerror", "onmessage", "onopen"]:
+            _attach_event_handler(self._js_websocket, attr, value)
+        else:
+            setattr(self._js_websocket, attr, value)
+
+    def send(self, data):
+        """
+        Send data through the WebSocket.
+
+        Accepts both text (str) and binary data (bytes, bytearray, etc.).
+        Binary data is automatically converted to a JavaScript Uint8Array.
+
+        ```python
+        # Send text.
+        ws.send("Hello server!")
+
+        # Send binary.
+        ws.send(bytes([1, 2, 3, 4]))
+        ws.send(bytearray([5, 6, 7, 8]))
+        ```
+
+        The WebSocket **must be in the OPEN state to send data**.
+        """
+        if isinstance(data, str):
+            self._js_websocket.send(data)
+        else:
+            buffer = js.Uint8Array.new(len(data))
+            for index, byte_value in enumerate(data):
+                buffer[index] = byte_value
+            self._js_websocket.send(buffer)
+
+    def close(self, code=None, reason=None):
+        """
+        Close the WebSocket connection. Optionally specify a `code` (integer)
+        and a `reason` (string) for closing the connection.
+
+        ```python
+        # Normal close.
+        ws.close()
+
+        # Close with code and reason.
+        ws.close(code=1000, reason="Task completed")
+        ```
+
+        Usage and values for `code` and `reasons` are explained here:
+
+        https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
+        """
+        if code and reason:
+            self._js_websocket.close(code, reason)
+        elif code:
+            self._js_websocket.close(code)
+        else:
+            self._js_websocket.close()
diff --git a/pyscript/workers.py b/pyscript/workers.py
new file mode 100644
index 0000000..4a104ba
--- /dev/null
+++ b/pyscript/workers.py
@@ -0,0 +1,191 @@
+"""
+Worker management for PyScript.
+
+This module provides access to named web workers defined in script tags, and
+utilities for dynamically creating workers from Python code.
+
+Named workers are Python web workers defined in HTML with a `name` attribute
+that can be referenced from the main thread or other workers. This module
+provides the `workers` object for accessing named workers and the
+`create_named_worker()` function for dynamically creating them.
+
+Accessing named workers:
+
+```html
+<!-- Define a named worker -->
+<script type="py" worker name="calculator">
+def add(a, b):
+    return a + b
+
+__export__ = ["add"]
+</script>
+
+<!-- Access from main thread -->
+<script type="mpy">
+from pyscript import workers
+
+
+calc = await workers["calculator"]
+result = await calc.add(5, 3)
+print(result)  # 8
+</script>
+```
+
+Dynamically creating named workers:
+
+```python
+from pyscript import create_named_worker
+
+
+# Create a worker from a Python file.
+worker = await create_named_worker(
+    src="./background_tasks.py",
+    name="task-processor"
+)
+
+# Use the worker's exported functions.
+result = await worker.process_data([1, 2, 3, 4, 5])
+print(result)
+```
+
+Key features:
+- Access (await) named workers via dictionary-like syntax.
+- Dynamically create workers from Python.
+- Cross-interpreter support (Pyodide and MicroPython).
+
+Worker access is asynchronous - you must await `workers[name]` to get
+a reference to the worker. This is because workers may not be ready
+immediately at startup.
+"""
+
+import js
+import json
+from polyscript import workers as _polyscript_workers
+
+
+class _ReadOnlyWorkersProxy:
+    """
+    A read-only proxy for accessing named web workers. Use
+    create_named_worker() to create new workers found in this proxy.
+
+    This provides dictionary-like access to named workers defined in
+    the page. It handles differences between Pyodide and MicroPython
+    implementations transparently.
+
+    (See: https://github.com/pyscript/pyscript/issues/2106 for context.)
+
+    The proxy is read-only to prevent accidental modification of the
+    underlying workers registry. Both item access and attribute access are
+    supported for convenience (especially since HTML attribute names may
+    not be valid Python identifiers).
+
+    ```python
+    from pyscript import workers
+
+    # Access a named worker.
+    my_worker = await workers["worker-name"]
+    result = await my_worker.some_function()
+
+    # Alternatively, if the name works, access via attribute notation.
+    my_worker = await workers.worker_name
+    result = await my_worker.some_function()
+    ```
+
+    **This is a proxy object, not a dict**. You cannot iterate over it or
+    get a list of worker names. This is intentional because worker
+    startup timing is non-deterministic.
+    """
+
+    def __getitem__(self, name):
+        """
+        Get a named worker by `name`. It returns a promise that resolves to
+        the worker reference when ready.
+
+        This is useful if the underlying worker name is not a valid Python
+        identifier.
+
+        ```python
+        worker = await workers["my-worker"]
+        ```
+        """
+        return js.Reflect.get(_polyscript_workers, name)
+
+    def __getattr__(self, name):
+        """
+        Get a named worker as an attribute. It returns a promise that resolves
+        to the worker reference when ready.
+
+        This allows accessing workers via dot notation as an alternative
+        to bracket notation.
+
+        ```python
+        worker = await workers.my_worker
+        ```
+        """
+        return js.Reflect.get(_polyscript_workers, name)
+
+
+# Global workers proxy for accessing named workers.
+workers = _ReadOnlyWorkersProxy()
+
+
+async def create_named_worker(src, name, config=None, type="py"):
+    """
+    Dynamically create a web worker with a `src` Python file, a unique
+    `name` and optional `config` (dict or JSON string) and `type` (`py`
+    for Pyodide or `mpy` for MicroPython, the default is `py`).
+
+    This function creates a new web worker by injecting a script tag into
+    the document. The worker will be accessible via the `workers` proxy once
+    it's ready.
+
+    It return a promise that resolves to the worker reference when ready.
+
+    ```python
+    from pyscript import create_named_worker
+
+
+    # Create a Pyodide worker.
+    worker = await create_named_worker(
+        src="./my_worker.py",
+        name="background-worker"
+    )
+
+    # Use the worker.
+    result = await worker.process_data()
+
+    # Create with standard PyScript configuration.
+    worker = await create_named_worker(
+        src="./processor.py",
+        name="data-processor",
+        config={"packages": ["numpy", "pandas"]}
+    )
+
+    # Use MicroPython instead.
+    worker = await create_named_worker(
+        src="./lightweight_worker.py",
+        name="micro-worker",
+        type="mpy"
+    )
+    ```
+
+    **The worker script should define** `__export__` to specify which
+    functions or objects are accessible from the main thread.
+    """
+    # Create script element for the worker.
+    script = js.document.createElement("script")
+    script.type = type
+    script.src = src
+    # Mark as a worker with a name.
+    script.setAttribute("worker", "")
+    script.setAttribute("name", name)
+    # Add configuration if provided.
+    if config:
+        if isinstance(config, str):
+            config_str = config
+        else:
+            config_str = json.dumps(config)
+        script.setAttribute("config", config_str)
+    # Inject the script into the document and await the result.
+    js.document.body.append(script)
+    return await workers[name]

From 583888656202cc7e36440bd9c543809f6bd50f31 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Mon, 8 Dec 2025 17:12:55 +0000
Subject: [PATCH 6/8] Update the structure of the API docs into separate pages,
 one for each submodule. All to be autogenerated from the source files in
 ./pyscript.

---
 docs/api.md           |  57 ------------------
 docs/api/context.md   |   3 +
 docs/api/display.md   |   3 +
 docs/api/events.md    |   3 +
 docs/api/fetch.md     |   3 +
 docs/api/ffi.md       |   3 +
 docs/api/flatted.md   |   3 +
 docs/api/fs.md        |   3 +
 docs/api/init.md      |  14 +++++
 docs/api/media.md     |   3 +
 docs/api/storage.md   |   3 +
 docs/api/util.md      |   3 +
 docs/api/web.md       |  18 ++++++
 docs/api/websocket.md |   3 +
 docs/api/workers.md   |   3 +
 mkdocs.yml            |  26 ++++++++-
 pyscript/__init__.py  | 113 ++++++++++++++++++++++++++----------
 pyscript/context.py   |  59 +++++++++++++------
 pyscript/display.py   |  27 ++++-----
 pyscript/events.py    |   5 +-
 pyscript/fetch.py     |  16 +++---
 pyscript/ffi.py       |  30 +++++-----
 pyscript/flatted.py   |  20 ++++---
 pyscript/fs.py        |  31 +++++-----
 pyscript/media.py     |  57 +++++++++---------
 pyscript/storage.py   |  40 +++++++------
 pyscript/util.py      |  16 +++---
 pyscript/web.py       | 131 ++++++++++++++++++++++++++----------------
 pyscript/websocket.py |  65 ++++++++++-----------
 pyscript/workers.py   |  23 ++++----
 30 files changed, 471 insertions(+), 313 deletions(-)
 delete mode 100644 docs/api.md
 create mode 100644 docs/api/context.md
 create mode 100644 docs/api/display.md
 create mode 100644 docs/api/events.md
 create mode 100644 docs/api/fetch.md
 create mode 100644 docs/api/ffi.md
 create mode 100644 docs/api/flatted.md
 create mode 100644 docs/api/fs.md
 create mode 100644 docs/api/init.md
 create mode 100644 docs/api/media.md
 create mode 100644 docs/api/storage.md
 create mode 100644 docs/api/util.md
 create mode 100644 docs/api/web.md
 create mode 100644 docs/api/websocket.md
 create mode 100644 docs/api/workers.md

diff --git a/docs/api.md b/docs/api.md
deleted file mode 100644
index 8285846..0000000
--- a/docs/api.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Built-in APIs
-
-## PyScript
-
-::: pyscript
-
-## Context
-
-::: pyscript.context
-
-## Display
-
-::: pyscript.display
-
-## Events
-
-::: pyscript.events
-
-## Fetch
-
-::: pyscript.fetch
-
-## FFI
-
-::: pyscript.ffi
-
-## Flatted
-
-::: pyscript.flatted
-
-## FS
-
-::: pyscript.fs
-
-## Media
-
-::: pyscript.media
-
-## Storage
-
-::: pyscript.storage
-
-## Util
-
-::: pyscript.util
-
-## Web
-
-::: pyscript.web
-
-## WebSocket
-
-::: pyscript.websocket
-
-## Workers
-
-::: pyscript.workers
diff --git a/docs/api/context.md b/docs/api/context.md
new file mode 100644
index 0000000..635214e
--- /dev/null
+++ b/docs/api/context.md
@@ -0,0 +1,3 @@
+# `pyscript.context`
+
+::: pyscript.context
diff --git a/docs/api/display.md b/docs/api/display.md
new file mode 100644
index 0000000..fb98686
--- /dev/null
+++ b/docs/api/display.md
@@ -0,0 +1,3 @@
+# `pyscript.display`
+
+::: pyscript.display
diff --git a/docs/api/events.md b/docs/api/events.md
new file mode 100644
index 0000000..061c4ae
--- /dev/null
+++ b/docs/api/events.md
@@ -0,0 +1,3 @@
+# `pyscript.event`
+
+::: pyscript.events
diff --git a/docs/api/fetch.md b/docs/api/fetch.md
new file mode 100644
index 0000000..c57937f
--- /dev/null
+++ b/docs/api/fetch.md
@@ -0,0 +1,3 @@
+# `pyscript.fetch`
+
+::: pyscript.fetch
diff --git a/docs/api/ffi.md b/docs/api/ffi.md
new file mode 100644
index 0000000..69b5472
--- /dev/null
+++ b/docs/api/ffi.md
@@ -0,0 +1,3 @@
+# `pyscript.ffi`
+
+::: pyscript.ffi
diff --git a/docs/api/flatted.md b/docs/api/flatted.md
new file mode 100644
index 0000000..e8052ff
--- /dev/null
+++ b/docs/api/flatted.md
@@ -0,0 +1,3 @@
+# `pyscript.flatted`
+
+::: pyscript.flatted
diff --git a/docs/api/fs.md b/docs/api/fs.md
new file mode 100644
index 0000000..6ef3363
--- /dev/null
+++ b/docs/api/fs.md
@@ -0,0 +1,3 @@
+# `pyscript.fs`
+
+::: pyscript.fs
diff --git a/docs/api/init.md b/docs/api/init.md
new file mode 100644
index 0000000..2da87b0
--- /dev/null
+++ b/docs/api/init.md
@@ -0,0 +1,14 @@
+# The `pyscript` API
+
+!!! important
+
+    These API docs are auto-generated from our source code. To suggest
+    changes or report errors, please do so via
+    [our GitHub repository](https://github.com/pyscript/pyscript). The
+    source code for these APIs
+    [is found here](https://github.com/pyscript/pyscript/tree/main/core/src/stdlib/pyscript)
+    in our repository.
+
+::: pyscript
+    options:
+        show_root_heading: false
diff --git a/docs/api/media.md b/docs/api/media.md
new file mode 100644
index 0000000..1b19777
--- /dev/null
+++ b/docs/api/media.md
@@ -0,0 +1,3 @@
+# `pyscript.media`
+
+::: pyscript.media
diff --git a/docs/api/storage.md b/docs/api/storage.md
new file mode 100644
index 0000000..053df3c
--- /dev/null
+++ b/docs/api/storage.md
@@ -0,0 +1,3 @@
+# `pyscript.storage`
+
+::: pyscript.storage
diff --git a/docs/api/util.md b/docs/api/util.md
new file mode 100644
index 0000000..d7e7db4
--- /dev/null
+++ b/docs/api/util.md
@@ -0,0 +1,3 @@
+# `pyscript.util`
+
+::: pyscript.util
diff --git a/docs/api/web.md b/docs/api/web.md
new file mode 100644
index 0000000..b1a3c1c
--- /dev/null
+++ b/docs/api/web.md
@@ -0,0 +1,18 @@
+# `pyscript.web`
+
+::: pyscript.web
+    options:
+      members:
+        - page
+        - Element
+        - ContainerElement
+        - ElementCollection
+        - Classes
+        - Style
+        - HasOptions
+        - Options
+        - Page
+        - canvas
+        - video
+        - CONTAINER_TAGS
+        - VOID_TAGS
diff --git a/docs/api/websocket.md b/docs/api/websocket.md
new file mode 100644
index 0000000..093fda8
--- /dev/null
+++ b/docs/api/websocket.md
@@ -0,0 +1,3 @@
+# `pyscript.websocket`
+
+::: pyscript.websocket
diff --git a/docs/api/workers.md b/docs/api/workers.md
new file mode 100644
index 0000000..2930a8d
--- /dev/null
+++ b/docs/api/workers.md
@@ -0,0 +1,3 @@
+# `pyscript.workers`
+
+::: pyscript.workers
diff --git a/mkdocs.yml b/mkdocs.yml
index 19298e6..2e0e698 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -60,7 +60,15 @@ plugins:
       css_dir: css
       javascript_dir: js
       canonical_version: null
-  - mkdocstrings
+  - mkdocstrings:
+      default_handler: python
+      locale: en
+      handlers:
+        python:
+          options:
+            show_source: true
+            members_order: source
+            show_symbol_type_heading: true
 
 nav:
   - Home: index.md
@@ -83,7 +91,21 @@ nav:
     - PyGame-CE: user-guide/pygame-ce.md
     - Plugins: user-guide/plugins.md
     - Use Offline: user-guide/offline.md
-  - Built-in APIs: api.md
+  - PyScript APIs:
+    - Introduction: api/init.md
+    - context: api/context.md
+    - display: api/display.md
+    - events: api/events.md
+    - fetch: api/fetch.md
+    - ffi: api/ffi.md
+    - flatted: api/flatted.md
+    - fs: api/fs.md
+    - media: api/media.md
+    - storage: api/storage.md
+    - util: api/util.md
+    - web: api/web.md
+    - websocket: api/websocket.md
+    - workers: api/workers.md
   - FAQ: faq.md
   - Contributing: contributing.md
   - Developer Guide: developers.md
diff --git a/pyscript/__init__.py b/pyscript/__init__.py
index 58e24bd..ecae1e4 100644
--- a/pyscript/__init__.py
+++ b/pyscript/__init__.py
@@ -1,45 +1,100 @@
 """
 This is the main `pyscript` namespace. It provides the primary Pythonic API
-for users to interact with PyScript features sitting on top of the browser's
-own API (https://developer.mozilla.org/en-US/docs/Web/API). It includes
-utilities for common activities such as displaying content, handling events,
-fetching resources, managing local storage, and coordinating with web workers.
+for users to interact with the
+[browser's own API](https://developer.mozilla.org/en-US/docs/Web/API). It 
+includes utilities for common activities such as displaying content, handling
+events, fetching resources, managing local storage, and coordinating with
+web workers.
 
-Some notes about the naming conventions and the relationship between various
-similar-but-different names found within this code base.
+The most important names provided by this namespace can be directly imported
+from `pyscript`, for example:
 
-`import pyscript`
+```python
+from pyscript import display, HTML, fetch, when, storage, WebSocket
+```
 
-This package contains the main user-facing API offered by pyscript. All
-the names which are supposed be used by end users should be made
-available in pyscript/__init__.py (i.e., this file).
+The following names are available in the `pyscript` namespace:
 
-`import _pyscript`
+- `RUNNING_IN_WORKER`: Boolean indicating if the code is running in a Web
+  Worker.
+- `PyWorker`: Class for creating Web Workers running Python code.
+- `config`: Configuration object for pyscript settings.
+- `current_target`: The element in the DOM that is the current target for
+  output.
+- `document`: The standard `document` object, proxied in workers.
+- `window`: The standard `window` object, proxied in workers.
+- `js_import`: Function to dynamically import JS modules.
+- `js_modules`: Object containing JS modules available to Python.
+- `sync`: Utility for synchronizing between worker and main thread.
+- `display`: Function to render Python objects in the web page.
+- `HTML`: Helper class to create HTML content for display.
+- `fetch`: Function to perform HTTP requests.
+- `Storage`: Class representing browser storage (local/session).
+- `storage`: Object to interact with browser's local storage.
+- `WebSocket`: Class to create and manage WebSocket connections.
+- `when`: Function to register event handlers on DOM elements.
+- `Event`: Class representing user defined or DOM events.
+- `py_import`: Function to lazily import Pyodide related Python modules.
 
-This is an internal module implemented in JS. It is used internally by
-the pyscript package, **end users should not use it directly**. For its
-implementation, grep for `interpreter.registerJsModule("_pyscript",
-...)` in `core.js`.
+If running in the main thread, the following additional names are available:
 
-`import js`
+- `create_named_worker`: Function to create a named Web Worker.
+- `workers`: Object to manage and interact with existing Web Workers.
 
-This is the JS `globalThis`, as exported by Pyodide and/or Micropython's
-foreign function interface (FFI). As such, it contains different things in
-the main thread or in a worker, as defined by web standards.
+All of these names are defined in the various submodules of `pyscript` and
+are imported and re-exported here for convenience. Please refer to the
+respective submodule documentation for more details on each component.
 
-`import pyscript.context`
 
-This submodule abstracts away some of the differences between the main
-thread and a worker. In particular, it defines `window` and `document`
-in such a way that these names work in both cases: in the main thread,
-they are the "real" objects, in a worker they are proxies which work
-thanks to [coincident](https://github.com/WebReflection/coincident).
+!!! Note
+    Some notes about the naming conventions and the relationship between 
+    various similar-but-different names found within this code base.
 
-`from pyscript import window, document`
+    ```python
+    import pyscript
+    ```
 
-These are just the `window` and `document` objects as defined by
-`pyscript.context`. This is the blessed way to access them from `pyscript`,
-as it works transparently in both the main thread and worker cases.
+    The `pyscript` package contains the main user-facing API offered by
+    PyScript. All the names which are supposed be used by end users should
+    be made available in `pyscript/__init__.py` (i.e., this source file).
+
+    ```python
+    import _pyscript
+    ```
+
+    The `_pyscript` module is an internal API implemented in JS. **End users
+    should not use it directly**. For its implementation, grep for 
+    `interpreter.registerJsModule("_pyscript",...)` in `core.js`.
+
+    ```python
+    import js
+    ```
+
+    The `js` object is the JS `globalThis`, as exported by Pyodide and/or
+    Micropython's foreign function interface (FFI). As such, it contains
+    different things in the main thread or in a worker, as defined by web
+    standards.
+
+    ```python
+    import pyscript.context
+    ```
+
+    The `context` submodule abstracts away some of the differences between
+    the main thread and a worker. Its most important features are made
+    available in the root `pyscript` namespace. All other functionality is
+    mostly for internal PyScript use or advanced users. In particular, it
+    defines `window` and `document` in such a way that these names work in
+    both cases: in the main thread, they are the "real" objects, in a worker
+    they are proxies which work thanks to 
+    [coincident](https://github.com/WebReflection/coincident).
+
+    ```python
+    from pyscript import window, document
+    ```
+
+    These are just the `window` and `document` objects as defined by
+    `pyscript.context`. This is the blessed way to access them from `pyscript`,
+    as it works transparently in both the main thread and worker cases.
 """
 
 from polyscript import lazy_py_modules as py_import
diff --git a/pyscript/context.py b/pyscript/context.py
index b5d8490..c685047 100644
--- a/pyscript/context.py
+++ b/pyscript/context.py
@@ -1,13 +1,16 @@
 """
 Execution context management for PyScript.
 
-This module handles the differences between running in the main browser thread
-versus running in a Web Worker, providing a consistent API regardless of the
-execution context.
+This module handles the differences between running in the
+[main browser thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread)
+versus running in a 
+[Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
+providing a consistent API regardless of the execution context.
 
 Key features:
+
 - Detects whether code is running in a worker or main thread. Read this via
-  `pyscript.context.RUNNING_IN_WORKER`.
+  the boolean `pyscript.context.RUNNING_IN_WORKER`.
 - Parses and normalizes configuration from `polyscript.config` and adds the
   Python interpreter type via the `type` key in `pyscript.context.config`.
 - Provides appropriate implementations of `window`, `document`, and `sync`.
@@ -17,16 +20,22 @@
 - Provides access to the current display target via
   `pyscript.context.display_target`.
 
-Main thread context:
-- `window` and `document` are available directly.
-- `PyWorker` can be created to spawn worker threads.
-- `sync` is not available (raises `NotSupported`).
+!!! warning
+
+    These are key differences between the main thread and worker contexts:
+
+    Main thread context:
 
-Worker context:
-- `window` and `document` are proxied from main thread (if SharedArrayBuffer
-  available).
-- `PyWorker` is not available (raises `NotSupported`).
-- `sync` utilities are available for main thread communication.
+    - `window` and `document` are available directly.
+    - `PyWorker` can be created to spawn worker threads.
+    - `sync` is not available (raises `NotSupported`).
+
+    Worker context:
+
+    - `window` and `document` are proxied from main thread (if SharedArrayBuffer
+    available).
+    - `PyWorker` is not available (raises `NotSupported`).
+    - `sync` utilities are available for main thread communication.
 """
 
 import json
@@ -37,14 +46,26 @@
 from polyscript import js_modules
 from pyscript.util import NotSupported
 
-# Detect execution context: True if running in a worker, False if main thread.
 RUNNING_IN_WORKER = not hasattr(js, "document")
+"""Detect execution context: True if running in a worker, False if main thread."""
 
-# Parse and normalize configuration from polyscript.
 config = json.loads(js.JSON.stringify(_polyscript_config))
+"""Parsed and normalized configuration."""
 if isinstance(config, str):
     config = {}
 
+js_import = None
+"""Function to import JavaScript modules dynamically."""
+
+window = None
+"""The `window` object (proxied if in a worker)."""
+
+document = None
+"""The `document` object (proxied if in a worker)."""
+
+sync = None
+"""Sync utilities for worker-main thread communication (only in workers)."""
+
 # Detect and add Python interpreter type to config.
 if "MicroPython" in sys.version:
     config["type"] = "mpy"
@@ -121,7 +142,6 @@ def __getattr__(self, field):
         js.console.warn(sab_error_message)
         window = NotSupported("pyscript.window", sab_error_message)
         document = NotSupported("pyscript.document", sab_error_message)
-        js_import = None
 
     # Worker-specific utilities for main thread communication.
     sync = polyscript.xworker.sync
@@ -135,9 +155,11 @@ def current_target():
 else:
     # Main thread context setup.
     import _pyscript
-    from _pyscript import PyWorker as _PyWorker, js_import
+    from _pyscript import PyWorker as _PyWorker
     from pyscript.ffi import to_js
 
+    js_import = _pyscript.js_import
+
     def PyWorker(url, **options):
         """
         Create a Web Worker running Python code.
@@ -149,12 +171,13 @@ def PyWorker(url, **options):
         ```python
         from pyscript import PyWorker
 
+
         # Create a worker to run background tasks.
         # (`type` MUST be either `micropython` or `pyodide`)
         worker = PyWorker("./worker.py", type="micropython")
         ```
 
-        PyWorker can only be created from the main thread, not from
+        PyWorker **can only be created from the main thread**, not from
         within another worker.
         """
         return _PyWorker(url, to_js(options))
diff --git a/pyscript/display.py b/pyscript/display.py
index 0af530a..69efd5d 100644
--- a/pyscript/display.py
+++ b/pyscript/display.py
@@ -3,21 +3,22 @@
 
 This module provides the `display()` function for rendering Python objects
 in the web page. The function introspects objects to determine the appropriate
-MIME type and rendering method.
+[MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types)
+and rendering method.
 
 Supported MIME types:
 
-    - `text/plain`: Plain text (HTML-escaped)
-    - `text/html`: HTML content
-    - `image/png`: PNG images as data URLs
-    - `image/jpeg`: JPEG images as data URLs
-    - `image/svg+xml`: SVG graphics
-    - `application/json`: JSON data
-    - `application/javascript`: JavaScript code (discouraged)
+- `text/plain`: Plain text (HTML-escaped)
+- `text/html`: HTML content
+- `image/png`: PNG images as data URLs
+- `image/jpeg`: JPEG images as data URLs
+- `image/svg+xml`: SVG graphics
+- `application/json`: JSON data
+- `application/javascript`: JavaScript code (discouraged)
 
 The `display()` function uses standard Python representation methods
 (`_repr_html_`, `_repr_png_`, etc.) to determine how to render objects.
-Object can provide a `_repr_mimebundle_` method to specify preferred formats
+Objects can provide a `_repr_mimebundle_` method to specify preferred formats
 like this:
 
 ```python
@@ -28,9 +29,8 @@ def _repr_mimebundle_(self):
     }
 ```
 
-Heavily inspired by IPython's rich display system. See:
-
-https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html
+Heavily inspired by
+[IPython's rich display system](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html).
 """
 
 import base64
@@ -95,7 +95,8 @@ class HTML:
     display(HTML("<h1>Hello World</h1>"))
     ```
 
-    Inspired by IPython.display.HTML.
+    Inspired by
+    [`IPython.display.HTML`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.HTML).
     """
 
     def __init__(self, html):
diff --git a/pyscript/events.py b/pyscript/events.py
index 925cd60..dd4fd22 100644
--- a/pyscript/events.py
+++ b/pyscript/events.py
@@ -86,13 +86,14 @@ def remove_listener(self, *listeners):
 
 def when(event_type, selector=None):
     """
-    A decorator to handle DOM events or custom Event objects.
+    A decorator to handle DOM events or custom `Event` objects.
 
     For DOM events, specify the `event_type` (e.g. `"click"`) and a `selector`
     for target elements. For custom `Event` objects, just pass the `Event`
     instance as the `event_type`. It's also possible to pass a list of `Event`
     objects. The `selector` is required only for DOM events. It should be a
-    CSS selector string, Element, ElementCollection, or list of DOM elements.
+    [CSS selector string](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors),
+    `Element`, `ElementCollection`, or list of DOM elements.
 
     The decorated function can be either a regular function or an async
     function. If the function accepts an argument, it will receive the event
diff --git a/pyscript/fetch.py b/pyscript/fetch.py
index 28cb4ad..97de453 100644
--- a/pyscript/fetch.py
+++ b/pyscript/fetch.py
@@ -1,8 +1,7 @@
 """
-A Pythonic wrapper around JavaScript's fetch API.
-
-This module provides a Python-friendly interface to the browser's fetch API,
-returning native Python data types and supported directly awaiting the promise
+This module provides a Python-friendly interface to the 
+[browser's fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API),
+returning native Python data types and supporting directly awaiting the promise
 and chaining method calls directly on the promise.
 
 ```python
@@ -11,7 +10,10 @@
 
 # Pattern 1: Await the response, then extract data.
 response = await fetch(url)
-data = await response.json()
+if response.ok:
+    data = await response.json()
+else:
+    raise NetworkError(f"Fetch failed: {response.status}")
 
 # Pattern 2: Chain method calls directly on the promise.
 data = await fetch(url).json()
@@ -160,8 +162,8 @@ def fetch(url, **options):
     - `headers`: Dict of request headers.
     - `body`: Request body (string, dict for JSON, etc.)
 
-    See the MDN documentation for details:
-    https://developer.mozilla.org/en-US/docs/Web/API/RequestInit
+    See [this documentation](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+    for more details of these web standards.
 
     The function returns a promise that resolves to a Response-like object
     with Pythonic methods to extract data:
diff --git a/pyscript/ffi.py b/pyscript/ffi.py
index 1100277..2394862 100644
--- a/pyscript/ffi.py
+++ b/pyscript/ffi.py
@@ -1,9 +1,8 @@
 """
-Consistent Foreign Function Interface (FFI) utilities for PyScript.
-
-This module provides a unified FFI layer that works consistently across both
-Pyodide and MicroPython, and in worker or main thread contexts, abstracting
-away the differences in their JavaScript interop APIs.
+This module provides a unified Foreign Function Interface (FFI) layer that
+works consistently across both Pyodide and MicroPython, and in worker or main
+thread contexts, abstracting away the differences in their JavaScript interop
+APIs.
 
 The following utilities work on both the main thread and in worker contexts:
 
@@ -18,10 +17,8 @@
 - `gather`: Collect multiple values from worker contexts.
 - `query`: Query objects in worker contexts.
 
-More details of the `direct`, `gather`, and `query` utilities can be found
-here:
-
-https://github.com/WebReflection/reflected-ffi?tab=readme-ov-file#remote-extra-utilities
+More details of the `direct`, `gather`, and `query` utilities
+[can be found here](https://github.com/WebReflection/reflected-ffi?tab=readme-ov-file#remote-extra-utilities).
 """
 
 try:
@@ -77,16 +74,19 @@ def to_js(value, **kw):
     """
     Convert Python objects to JavaScript objects.
 
-    This ensures Python dicts become proper JavaScript objects rather
-    than Maps, which is more intuitive for most use cases.
+    This ensures a Python `dict` becomes a 
+    [proper JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+    rather a JavaScript [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
+    which is more intuitive for most use cases.
 
-    Where required, the underlying to_js uses Object.fromEntries for dict
-    conversion.
+    Where required, the underlying `to_js` uses `Object.fromEntries` for
+    `dict` conversion.
 
     ```python
     from pyscript import ffi
     import js
 
+    
     note = {
         "body": "This is a notification",
         "icon": "icon.png"
@@ -111,6 +111,7 @@ def is_none(value):
     from pyscript import ffi
     import js
 
+    
     val1 = None
     val2 = js.null
     val3 = 42
@@ -145,7 +146,8 @@ def is_none(value):
 
 def assign(source, *args):
     """
-    Merge JavaScript objects (like Object.assign).
+    Merge JavaScript objects (like
+    [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)).
 
     Takes a target object and merges properties from one or more source
     objects into it, returning the modified target.
diff --git a/pyscript/flatted.py b/pyscript/flatted.py
index 73fa82d..b001b36 100644
--- a/pyscript/flatted.py
+++ b/pyscript/flatted.py
@@ -1,10 +1,8 @@
 """
-Circular JSON parser for Python.
-
-This module is a Python implementation of the Flatted JavaScript library
-(https://www.npmjs.com/package/flatted), which provides a super light and
-fast way to serialize and deserialize JSON structures that contain circular
-references.
+This module is a Python implementation of the 
+[Flatted JavaScript library](https://www.npmjs.com/package/flatted), which
+provides a light and fast way to serialize and deserialize JSON structures
+that contain circular references.
 
 Standard JSON cannot handle circular references - attempting to serialize an
 object that references itself will cause an error. Flatted solves this by
@@ -12,13 +10,15 @@
 serialized and later reconstructed.
 
 Common use cases:
-- Serializing complex object graphs with circular references
-- Working with DOM-like structures that contain parent/child references
-- Preserving object identity when serializing data structures
+
+- Serializing complex object graphs with circular references.
+- Working with DOM-like structures that contain parent/child references.
+- Preserving object identity when serializing data structures.
 
 ```python
 from pyscript import flatted
 
+
 # Create a circular structure.
 obj = {"name": "parent"}
 obj["self"] = obj  # Circular reference!
@@ -157,6 +157,7 @@ def parse(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
+    
     # Parse a Flatted JSON string.
     json_string = '[{"name": "1", "self": "0"}, "parent"]'
     obj = flatted.parse(json_string)
@@ -201,6 +202,7 @@ def stringify(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
+    
     # Create an object with a circular reference.
     parent = {"name": "parent", "children": []}
     child = {"name": "child", "parent": parent}
diff --git a/pyscript/fs.py b/pyscript/fs.py
index 58cfc4d..ec31282 100644
--- a/pyscript/fs.py
+++ b/pyscript/fs.py
@@ -1,16 +1,12 @@
 """
-Filesystem mounting for Chromium-based browsers.
-
 This module provides an API for mounting directories from the user's local
-filesystem into the browser's virtual filesystem. This allows Python code
-running in the browser to read and write files on the user's local machine.
-
-**Important:** This API only works in Chromium-based browsers (Chrome, Edge,
-Opera, Brave, etc.) that support the File System Access API.
+filesystem into the browser's virtual filesystem. This means Python code,
+running in the browser, can read and write files on the user's local machine.
 
-For technical details of the underlying Chromium based API, see:
-
-https://wicg.github.io/file-system-access/
+!!! warning
+    **This API only works in Chromium-based browsers** (Chrome, Edge,
+    Opera, Brave, etc.) that support the 
+    [File System Access API](https://wicg.github.io/file-system-access/).
 
 The module maintains a `mounted` dictionary that tracks all currently mounted
 paths and their associated filesystem handles.
@@ -18,6 +14,7 @@
 ```python
 from pyscript import fs, document, when
 
+
 # Mount a local directory to the `/local` mount point in the browser's
 # virtual filesystem (may prompt user for permission).
 await fs.mount("/local")
@@ -52,8 +49,8 @@ async def handler(event):
     from pyscript.context import sync as sync_with_worker
     from polyscript import IDBMap
 
-# Global dictionary tracking mounted paths and their filesystem handles.
 mounted = {}
+"""Global dictionary tracking mounted paths and their filesystem handles."""
 
 
 async def _check_permission(details):
@@ -81,6 +78,7 @@ async def mount(path, mode="readwrite", root="", id="pyscript"):
     ```python
     from pyscript import fs
 
+    
     # Basic mount with default settings.
     await fs.mount("/local")
 
@@ -164,6 +162,7 @@ async def sync(path):
     ```python
     from pyscript import fs
 
+    
     await fs.mount("/local")
 
     # Make changes to files.
@@ -195,6 +194,7 @@ async def unmount(path):
     ```python
     from pyscript import fs
 
+    
     await fs.mount("/local")
     # ... work with files ...
     await fs.unmount("/local")
@@ -203,7 +203,7 @@ async def unmount(path):
     await fs.mount("/local", id="different-folder")
     ```
 
-    This automatically calls sync() before unmounting to ensure no data
+    This automatically calls `sync()` before unmounting to ensure no data
     is lost.
     """
     if path not in mounted:
@@ -220,13 +220,14 @@ async def revoke(path, id="pyscript"):
     `path` and `id` combination.
 
     This removes the stored permission for accessing the user's local
-    filesystem at the specified path and ID. Unlike unmount(), which only
-    removes the mount point, revoke() also clears the permission so the
+    filesystem at the specified path and ID. Unlike `unmount()`, which only
+    removes the mount point, `revoke()` also clears the permission so the
     user will be prompted again on next mount.
 
     ```python
     from pyscript import fs
 
+    
     await fs.mount("/local", id="my-app")
     # ... work with files ...
 
@@ -238,7 +239,7 @@ async def revoke(path, id="pyscript"):
     ```
 
     After revoking, the user will need to grant permission again and
-    select a directory when mount() is called next time.
+    select a directory when `mount()` is called next time.
     """
     mount_key = f"{path}@{id}"
 
diff --git a/pyscript/media.py b/pyscript/media.py
index 716331f..c541b14 100644
--- a/pyscript/media.py
+++ b/pyscript/media.py
@@ -1,8 +1,7 @@
 """
-Media device access for PyScript.
-
-This module provides classes and functions for interacting with media devices
-and streams in the browser, enabling you to work with cameras, microphones,
+This module provides classes and functions for interacting with
+[media devices and streams](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capture_and_Streams_API)
+in the browser, enabling you to work with cameras, microphones,
 and other media input/output devices directly from Python.
 
 Use this module for:
@@ -12,11 +11,11 @@
 - Enumerating available media devices.
 - Applying constraints to media streams (resolution, frame rate, etc.).
 
-
 ```python
 from pyscript import document
 from pyscript.media import Device, list_devices
 
+
 # Get a video stream from the default camera.
 stream = await Device.request_stream(video=True)
 
@@ -42,16 +41,18 @@ class Device:
     """
     Represents a media input or output device.
 
-    This class wraps a browser MediaDeviceInfo object, providing Pythonic
-    access to device properties like ID, label, and kind (audio/video
-    input/output).
+    This class wraps a browser 
+    [MediaDeviceInfo object](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo),
+    providing Pythonic access to device properties like `ID`, `label`, and
+    `kind` (audio/video, input/output).
 
-    Devices are typically obtained via `list_devices()` rather than
-    constructed directly.
+    Devices are typically obtained via the `list_devices()` function in this
+    module, rather than constructed directly.
 
     ```python
     from pyscript.media import list_devices
 
+    
     # Get all available devices.
     devices = await list_devices()
 
@@ -75,7 +76,7 @@ def id(self):
         """
         Unique identifier for this device.
 
-        This ID persists across sessions but is reset when the user clears
+        This `ID` persists across sessions but is reset when the user clears
         cookies. It's unique to the origin of the calling application.
         """
         return self._device_info.deviceId
@@ -86,14 +87,14 @@ def group(self):
         Group identifier for related devices.
 
         Devices belonging to the same physical device (e.g., a monitor with
-        both a camera and microphone) share the same group ID.
+        both a camera and microphone) share the same `group ID`.
         """
         return self._device_info.groupId
 
     @property
     def kind(self):
         """
-        Device type: "videoinput", "audioinput", or "audiooutput".
+        Device type: `"videoinput"`, `"audioinput"`, or `"audiooutput"`.
         """
         return self._device_info.kind
 
@@ -102,7 +103,7 @@ def label(self):
         """
         Human-readable description of the device.
 
-        Example: "External USB Webcam" or "Built-in Microphone".
+        Example: `"External USB Webcam"` or `"Built-in Microphone"`.
         """
         return self._device_info.label
 
@@ -110,7 +111,7 @@ def __getitem__(self, key):
         """
         Support bracket notation for JavaScript interop.
 
-        Allows accessing properties via device["id"] syntax. Necessary
+        Allows accessing properties via `device["id"]` syntax. Necessary
         when Device instances are proxied to JavaScript.
         """
         return getattr(self, key)
@@ -127,14 +128,14 @@ async def request_stream(cls, audio=False, video=True):
 
         Simple boolean constraints for `audio` and `video` can be used to
         request default devices. More complex constraints can be specified as
-        dictionaries conforming to the MediaTrackConstraints interface. See:
-
-        https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+        dictionaries conforming to
+        [the MediaTrackConstraints interface](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints).
 
         ```python
         from pyscript import document
         from pyscript.media import Device
 
+        
         # Get default video stream.
         stream = await Device.request_stream()
 
@@ -169,10 +170,11 @@ async def request_stream(cls, audio=False, video=True):
     @classmethod
     async def load(cls, audio=False, video=True):
         """
-        Deprecated: Use request_stream() instead.
+        !!! warning
+            **Deprecated: Use `request_stream()` instead.**
 
-        This method is retained for backwards compatibility but will be
-        removed in a future release. Please use request_stream() instead.
+            This method is retained for backwards compatibility but will be
+            removed in a future release. Please use `request_stream()` instead.
         """
         return await cls.request_stream(audio=audio, video=video)
 
@@ -183,6 +185,7 @@ async def get_stream(self):
         ```python
         from pyscript.media import list_devices
 
+        
         # List all devices.
         devices = await list_devices()
 
@@ -210,14 +213,13 @@ async def get_stream(self):
 
 async def list_devices():
     """
-    List all available media input and output devices.
-
     Returns a list of all media devices currently available to the browser,
     such as microphones, cameras, and speakers.
 
     ```python
     from pyscript.media import list_devices
 
+    
     # Get all devices.
     devices = await list_devices()
 
@@ -232,13 +234,14 @@ async def list_devices():
     ```
 
     The returned list will omit devices that are blocked by the document
-    Permission Policy (microphone, camera, speaker-selection) or for
+    [Permission Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy)
+    (microphone, camera, speaker-selection) or for
     which the user has not granted explicit permission.
 
     For security and privacy, device labels may be empty strings until
-    permission is granted. See:
-
-    https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
+    permission is granted. See
+    [this document](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)
+    for more information about this web standard.
     """
     device_infos = await window.navigator.mediaDevices.enumerateDevices()
     return [Device(device_info) for device_info in device_infos]
diff --git a/pyscript/storage.py b/pyscript/storage.py
index 3a13f7e..ca2fe6c 100644
--- a/pyscript/storage.py
+++ b/pyscript/storage.py
@@ -1,9 +1,8 @@
 """
-Persistent browser storage with a Pythonic dict-like interface.
-
-This module wraps the browser's IndexedDB persistent storage to provide a
-familiar Python dictionary API. Data is automatically serialized and
-persisted, surviving page reloads and browser restarts.
+This module wraps the browser's
+[IndexedDB persistent storage](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
+to provide a familiar Python dictionary API. Data is automatically
+serialized and persisted, surviving page reloads and browser restarts.
 
 Storage is persistent per origin (domain), isolated between different sites
 for security. Browsers typically allow each origin to store up to 10-60% of
@@ -11,7 +10,7 @@
 
 What this module provides:
 
-- Dict-like API (get, set, delete, iterate).
+- A `dict`-like API (get, set, delete, iterate).
 - Automatic serialization of common Python types.
 - Background persistence with optional explicit `sync()`.
 - Support for custom `Storage` subclasses.
@@ -19,6 +18,7 @@
 ```python
 from pyscript import storage
 
+
 # Create or open a named storage.
 my_data = await storage("user-preferences")
 
@@ -35,16 +35,17 @@
 theme = my_data.get("theme", "light")
 ```
 
-Common types are automatically serialized: bool, int, float, str, None,
-list, dict, tuple. Binary data (bytearray, memoryview) can be stored as
+Common types are automatically serialized: `bool`, `int`, `float`, `str`, `None`,
+`list`, `dict`, `tuple`. Binary data (`bytearray`, `memoryview`) can be stored as
 single values but not nested in structures.
 
 Tuples are deserialized as lists due to IndexedDB limitations.
 
-Browsers typically allow 10-60% of total disk space per origin. Chrome
-and Edge allow up to 60%, Firefox up to 10 GiB (or 10% of disk, whichever
-is smaller). Safari varies by app type. These limits are unlikely to be
-reached in typical usage.
+!!! info
+    Browsers typically allow 10-60% of total disk space per origin. Chrome
+    and Edge allow up to 60%, Firefox up to 10 GiB (or 10% of disk, whichever
+    is smaller). Safari varies by app type. These limits are unlikely to be
+    reached in typical usage.
 """
 
 from polyscript import storage as _polyscript_storage
@@ -97,7 +98,7 @@ def _convert_from_idb(value):
 
 class Storage(dict):
     """
-    A persistent dictionary backed by browser IndexedDB.
+    A persistent dictionary backed by the browser's IndexedDB.
 
     This class provides a dict-like interface with automatic persistence.
     Changes are queued for background writing, with optional explicit
@@ -108,6 +109,7 @@ class Storage(dict):
     ```python
     from pyscript import storage
 
+    
     # Open a storage.
     prefs = await storage("preferences")
 
@@ -128,6 +130,7 @@ class Storage(dict):
     ```python
     from pyscript import storage, Storage, window
 
+    
     class LoggingStorage(Storage):
         def __setitem__(self, key, value):
             window.console.log(f"Setting {key} = {value}")
@@ -173,7 +176,7 @@ def clear(self):
         """
         Remove all items from storage.
 
-        The clear operation is queued for persistence. Use `sync()` to ensure
+        The `clear()` operation is queued for persistence. Use `sync()` to ensure
         immediate completion.
         """
         self._store.clear()
@@ -184,7 +187,7 @@ async def sync(self):
         Force immediate synchronization to IndexedDB.
 
         By default, storage operations are queued and written asynchronously.
-        Call `sync()` when you need to guarantee data is persisted immediately,
+        Call `sync()` when you need to guarantee changes are persisted immediately,
         such as before critical operations or page unload.
 
         ```python
@@ -210,13 +213,14 @@ async def storage(name="", storage_class=Storage):
     If the storage doesn't exist, it will be created. If it does exist,
     its current contents will be loaded.
 
-    This function returns a Storage instance (or custom subclass instance)
-    acting as a persistent dictionary. A ValueError is raised if `name` is
+    This function returns a `Storage` instance (or custom subclass instance)
+    acting as a persistent dictionary. A `ValueError` is raised if `name` is
     empty or not provided.
 
     ```python
     from pyscript import storage
 
+    
     # Basic usage.
     user_data = await storage("user-profile")
     user_data["name"] = "Alice"
@@ -236,7 +240,7 @@ def __setitem__(self, key, value):
     validated = await storage("validated-data", ValidatingStorage)
     ```
 
-    Storage names are automatically prefixed with "@pyscript/" to
+    Storage names are automatically prefixed with `"@pyscript/"` to
     namespace them within IndexedDB.
     """
     if not name:
diff --git a/pyscript/util.py b/pyscript/util.py
index bbc1c35..4f45dcb 100644
--- a/pyscript/util.py
+++ b/pyscript/util.py
@@ -1,6 +1,4 @@
 """
-Utility functions for PyScript.
-
 This module contains general-purpose utility functions that don't fit into
 more specific modules. These utilities handle cross-platform compatibility
 between Pyodide and MicroPython, feature detection, and common type
@@ -20,7 +18,7 @@
 
 def as_bytearray(buffer):
     """
-    Given a JavaScript ArrayBuffer, convert it to a Python bytearray in a
+    Given a JavaScript `ArrayBuffer`, convert it to a Python `bytearray` in a
     MicroPython friendly manner.
     """
     ui8a = js.Uint8Array.new(buffer)
@@ -57,13 +55,16 @@ def __call__(self, *args):
 def is_awaitable(obj):
     """
     Returns a boolean indication if the passed in obj is an awaitable
-    function. (MicroPython treats awaitables as generator functions, and if
-    the object is a closure containing an async function we need to work
-    carefully.)
+    function. This is interpreter agnostic.
+    
+    !!! info 
+        MicroPython treats awaitables as generator functions, and if
+        the object is a closure containing an async function or a bound method
+        we need to work carefully.
     """
     from pyscript import config
 
-    if config["type"] == "mpy":  # Is MicroPython?
+    if config["type"] == "mpy":
         # MicroPython doesn't appear to have a way to determine if a closure is
         # an async function except via the repr. This is a bit hacky.
         r = repr(obj)
@@ -72,6 +73,7 @@ def is_awaitable(obj):
         # Same applies to bound methods.
         if "<bound_method" in r and "<generator>" in r:
             return True
+        # In MicroPython, generator functions are awaitable.
         return inspect.isgeneratorfunction(obj)
 
     return inspect.iscoroutinefunction(obj)
diff --git a/pyscript/web.py b/pyscript/web.py
index 43d8bd4..4b93261 100644
--- a/pyscript/web.py
+++ b/pyscript/web.py
@@ -1,13 +1,16 @@
 """
 A lightweight Pythonic interface to the DOM and HTML elements that helps you
-to interact with web pages, making it easy to find, create, manipulate, and
+interact with web pages, making it easy to find, create, manipulate, and
 compose HTML elements from Python.
 
+Highlights include:
+
 Use the `page` object to find elements on the current page:
 
 ```python
 from pyscript import web
 
+
 # Find by CSS selector (returns an ElementCollection).
 divs = web.page.find("div")
 buttons = web.page.find(".button-class")
@@ -67,7 +70,7 @@
 )
 ```
 
-An element's CSS classes behave like Python sets:
+An element's CSS classes behave like a Python `set`:
 
 ```python
 # Add and remove classes
@@ -86,7 +89,7 @@
 element.classes.discard("maybe-not-there")
 ```
 
-An element's styles behave like Python dictionaries:
+An element's styles behave like a Python `dict`:
 
 ```python
 # Set individual styles.
@@ -102,7 +105,7 @@
     print(f"Color is {element.style['color']}")
 ```
 
-Update multiple elements at once via an ElementCollection:
+Update multiple elements at once via an `ElementCollection`:
 
 ```python
 # Find multiple elements (returns an ElementCollection).
@@ -177,7 +180,7 @@ def another_handler(event):
 button = web.button("Click", on_click=handle_click)
 ```
 
-All Element instances provide direct access to the underlying DOM element
+All `Element` instances provide direct access to the underlying DOM element
 via attribute delegation:
 
 ```python
@@ -186,7 +189,7 @@ def another_handler(event):
 element.focus()
 element.blur()
 
-# But we do have a convenience method for scrolling into view.
+# But we do have a historic convenience method for scrolling into view.
 element.show_me()  # Calls scrollIntoView()
 
 # Access the raw DOM element when needed for special cases.
@@ -235,13 +238,14 @@ def _find_and_wrap(dom_node, selector):
 
 class Element:
     """
-    The base class for all HTML elements.
+    The base class for all [HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements).
 
     Provides a Pythonic interface to DOM elements with support for attributes,
     events, styles, classes, and DOM manipulation. It can create new elements
     or wrap existing DOM elements.
 
-    Elements are typically created using the tag-specific classes:
+    Elements are typically created using the tag-specific classes found
+    within this namespace (e.g. `web.div`, `web.span`, `web.button`):
 
     ```python
     from pyscript import web
@@ -262,13 +266,22 @@ class Element:
     )
     ```
 
+    !!! info
+
+        Some elements have an underscore suffix in their class names (e.g.
+        `select_`, `input_`).
+        
+        This is to avoid clashes with Python keywords. The underscore is removed
+        when determining the actual HTML tag name.
+
     Wrap existing DOM elements found on the page:
 
     ```python
-    # Find and wrap an element.
-    existing = web.page.find("#my-element")[0]
+    # Find and wrap an element by CSS selector.
+    existing = web.page.find(".my_class")[0]
 
-    # Or, better, just use direct ID lookup.
+    # Or, better, just use direct ID lookup (with or without the 
+    # leading '#').
     existing = web.page["my-element"]
     ```
 
@@ -290,7 +303,7 @@ class Element:
     div.textContent = "Plain text"
     ```
 
-    CSS classes are managed through a set-like interface:
+    CSS classes are managed through a `set`-like interface:
 
     ```python
     # Add classes.
@@ -310,7 +323,7 @@ class Element:
         print(cls)
     ```
 
-    Explicit CSS styles are managed through a dict-like interface:
+    Explicit CSS styles are managed through a `dict`-like interface:
 
     ```python
     # Set styles using CSS property names (hyphenated).
@@ -380,14 +393,17 @@ def handle_click(event):
     )
     ```
 
-    **Some HTML attributes clash with Python keywords and use trailing
-    underscores**:
+    !!! warning
+        **Some HTML attributes clash with Python keywords and use trailing
+        underscores**.
+    
+    Use `for_` instead of `for`, and `class_` instead of `class`.
 
     ```python
     # The 'for' attribute (on labels)
     label = web.label("Username", for_="username-input")
 
-    # The 'class' attribute (though 'classes' is preferred)
+    # The 'class' attribute (although 'classes' is preferred)
     div.class_ = "my-class"
     ```
 
@@ -522,7 +538,8 @@ def __setattr__(self, name, value):
         Set an attribute on the element.
 
         Private attributes (starting with `_`) are set on the Python object.
-        Public attributes are set on the underlying DOM element.
+        Public attributes are set on the underlying DOM element. Attributes
+        starting with `on_` are treated as events.
         """
         if name.startswith("_"):
             super().__setattr__(name, value)
@@ -578,7 +595,7 @@ def children(self):
     @property
     def classes(self):
         """
-        Return the element's CSS classes as a set-like object.
+        Return the element's CSS classes as a `set`-like `Classes` object.
 
         Supports set operations: `add`, `remove`, `discard`, `clear`.
         Check membership with `in`, iterate with `for`, get length with `len()`.
@@ -596,9 +613,10 @@ def classes(self):
     @property
     def style(self):
         """
-        Return the element's CSS styles as a dict-like object.
+        Return the element's CSS styles as a `dict`-like `Style` object.
 
-        Access using dict-style syntax with CSS property names (hyphenated).
+        Access using `dict`-style syntax with standard
+        [CSS property names (hyphenated)](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference).
 
         ```python
         element.style["background-color"] = "red"
@@ -657,7 +675,8 @@ def clone(self, clone_id=None):
 
     def find(self, selector):
         """
-        Find all descendant elements matching the CSS selector.
+        Find all descendant elements matching the 
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
         Returns an `ElementCollection` (possibly empty).
 
@@ -698,10 +717,8 @@ def update(self, classes=None, style=None, **kwargs):
 
 class Classes(set):
     """
-    A set of CSS class names that syncs with the DOM.
-
-    Behaves like a Python set with changes automatically reflected in the
-    element's classList.
+    Behaves like a Python `set` with changes automatically reflected in the
+    element's `classList`.
 
     ```python
     # Add and remove classes.
@@ -723,6 +740,7 @@ class Classes(set):
     """
 
     def __init__(self, element):
+        """Initialise the Classes set for the given element."""
         self._class_list = element._dom_element.classList
         super().__init__(self._class_list)
 
@@ -766,10 +784,8 @@ def clear(self):
 
 class Style(dict):
     """
-    A dictionary of CSS styles that syncs with the DOM.
-
-    Behaves like a Python dict with changes automatically reflected in the
-    element's style attribute.
+    Behaves like a Python `dict` with changes automatically reflected in the
+    element's `style` attribute.
 
     ```python
     # Set and get styles using CSS property names (hyphenated).
@@ -790,6 +806,7 @@ class Style(dict):
     """
 
     def __init__(self, element):
+        """Initialise the Style dict for the given element."""
         self._style = element._dom_element.style
         super().__init__()
 
@@ -808,7 +825,7 @@ class HasOptions:
     """
     Mixin for elements with options (`datalist`, `optgroup`, `select`).
 
-    Provides an options property that returns an `Options` instance. Used
+    Provides an `options` property that returns an `Options` instance. Used
     in conjunction with the `Options` class.
 
     ```python
@@ -833,7 +850,7 @@ class HasOptions:
 
     @property
     def options(self):
-        """Return this element's options as an Options instance."""
+        """Return this element's options as an `Options` instance."""
         if not hasattr(self, "_options"):
             self._options = Options(self)
         return self._options
@@ -933,7 +950,7 @@ def clear(self):
 
     def remove(self, index):
         """
-        Remove the option at the specified index.
+        Remove the option at the specified `index`.
         """
         self._element._dom_element.remove(index)
 
@@ -978,8 +995,9 @@ def __init__(
         Create a container element with optional `children`.
 
         Children can be passed as positional `*args` or via the `children`
-        keyword argument. String children are inserted as HTML. The `style`,
-        `classes`, and `**kwargs` are passed to the base `Element` initializer.
+        keyword argument. String children are inserted as unescaped HTML. The
+        `style`, `classes`, and `**kwargs` are passed to the base `Element`
+        initializer.
         """
         super().__init__(
             dom_element=dom_element, style=style, classes=classes, **kwargs
@@ -997,7 +1015,7 @@ def __iter__(self):
 
 class ElementCollection:
     """
-    A collection of Element instances with list-like operations.
+    A collection of Element instances with `list`-like operations.
 
     Supports iteration, indexing, slicing, and finding descendants.
     For bulk operations, iterate over the collection explicitly or use
@@ -1022,7 +1040,7 @@ class ElementCollection:
         item.innerHTML = "Updated"
         item.classes.add("processed")
 
-    # Bulk update all elements.
+    # Bulk update all contained elements.
     items.update_all(innerHTML="Hello", className="updated")
 
     # Find matches within the collection.
@@ -1036,7 +1054,7 @@ class ElementCollection:
     @classmethod
     def wrap_dom_elements(cls, dom_elements):
         """
-        Wrap an iterable of DOM elements in an ElementCollection.
+        Wrap an iterable of DOM elements in an `ElementCollection`.
         """
         return cls(
             [Element.wrap_dom_element(dom_element) for dom_element in dom_elements]
@@ -1098,13 +1116,14 @@ def __repr__(self):
     @property
     def elements(self):
         """
-        Return the underlying list of elements.
+        Return the underlying `list` of elements.
         """
         return self._elements
 
     def find(self, selector):
         """
-        Find all descendants matching the CSS selector.
+        Find all descendants matching the 
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
         Searches within all elements in the collection.
 
@@ -1138,9 +1157,9 @@ def update_all(self, **kwargs):
 
 class canvas(ContainerElement):
     """
-    HTML canvas element with drawing and download capabilities.
-
-    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas
+    A bespoke 
+    [HTML canvas element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas)
+    with Pythonic drawing and download capabilities.
     """
 
     def download(self, filename="snapped.png"):
@@ -1177,9 +1196,9 @@ def draw(self, what, width=None, height=None):
 
 class video(ContainerElement):
     """
-    HTML video element with snapshot capability.
-
-    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video
+    A bespoke
+    [HTML video element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video)
+    with Pythonic snapshot capability (to render an image to a canvas).
     """
 
     def snap(self, to=None, width=None, height=None):
@@ -1262,6 +1281,10 @@ class select(ContainerElement, HasOptions):
     "var",
     "wbr",
 ]
+"""
+Container elements that can have children. Each becomes a class in the
+`pyscript.web` namespace and corresponds to an HTML tag.
+"""
 # fmt: on
 
 # Void elements that cannot have children.
@@ -1278,6 +1301,10 @@ class select(ContainerElement, HasOptions):
     "source",
     "track",
 ]
+"""
+Void elements that cannot have children. Each becomes a class in the
+`pyscript.web` namespace and corresponds to an HTML tag.
+"""
 
 
 def _create_element_classes():
@@ -1321,8 +1348,8 @@ class Page:
     """
     Represents the current web page.
 
-    Provides access to the document's html, head, and body elements, plus
-    convenience methods for finding elements and appending to the body.
+    Provides access to the document's `html`, `head`, and `body` elements,
+    plus convenience methods for finding elements and appending to the body.
 
     ```python
     from pyscript import web
@@ -1372,20 +1399,20 @@ def __getitem__(self, key):
     @property
     def title(self):
         """
-        Get the page title.
+        Get the page `title`.
         """
         return document.title
 
     @title.setter
     def title(self, value):
         """
-        Set the page title.
+        Set the page `title`.
         """
         document.title = value
 
     def append(self, *items):
         """
-        Append items to the page body.
+        Append items to the page `body`.
 
         Shortcut for `page.body.append(*items)`.
         """
@@ -1393,7 +1420,8 @@ def append(self, *items):
 
     def find(self, selector):
         """
-        Find all elements matching the CSS selector.
+        Find all elements matching the
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
         Returns an `ElementCollection` of matching elements.
 
@@ -1408,3 +1436,4 @@ def find(self, selector):
 
 
 page = Page()
+"""A reference to the current web page. An instance of the `Page` class."""
diff --git a/pyscript/websocket.py b/pyscript/websocket.py
index 5d9874c..9fbd227 100644
--- a/pyscript/websocket.py
+++ b/pyscript/websocket.py
@@ -1,7 +1,6 @@
 """
-WebSocket support for PyScript.
-
-This module provides a Pythonic wrapper around the browser's WebSocket API,
+This module provides a Pythonic wrapper around the browser's
+[WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket),
 enabling two-way communication with WebSocket servers.
 
 Use this for real-time applications:
@@ -15,9 +14,9 @@
 - Naming deliberately follows the JavaScript WebSocket API closely for
   familiarity.
 
-See the Python docs for an explanation of memoryview:
+See the Python docs for 
+[an explanation of memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview).
 
-https://docs.python.org/3/library/stdtypes.html#memoryview
 
 ```python
 from pyscript import WebSocket
@@ -38,9 +37,6 @@ def on_close(event):
 ws.onmessage = on_message
 ws.onclose = on_close
 ```
-
-For more information about the underlying WebSocket API, see:
-https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
 """
 
 import js
@@ -73,7 +69,8 @@ async def async_wrapper(event):
 
 class WebSocketEvent:
     """
-    A read-only wrapper for WebSocket event objects.
+    A read-only wrapper for
+    [WebSocket event objects](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent).
 
     This class wraps browser WebSocket events and provides convenient access
     to event properties. It handles the conversion of binary data from
@@ -105,7 +102,7 @@ def __getattr__(self, attr):
         Get an attribute `attr` from the underlying event object.
 
         Handles special conversion of binary data from JavaScript typed
-        arrays to Python memoryview objects.
+        arrays to Python `memoryview` objects.
         """
         value = getattr(self._event, attr)
         if attr == "data" and not isinstance(value, str):
@@ -124,11 +121,10 @@ class WebSocket:
     handling communication with WebSocket servers. It supports both text and
     binary data transmission.
 
-    It's possible to access the underlying WebSocket methods and properties
-    directly if needed. However, the wrapper provides a more Pythonic API.
-
-    If you need to work with the raw JavaScript WebSocket instance, you can
-    access it via the `_js_websocket` attribute.
+    Access the underlying WebSocket methods and properties directly if needed.
+    However, the wrapper provides a more Pythonic API. If you need to work
+    with the raw JavaScript WebSocket instance, you can access it via the 
+    `_js_websocket` attribute.
 
     Using textual (`str`) data:
 
@@ -169,7 +165,8 @@ def handle_message(event):
     ws.send(data)
     ```
 
-    See: https://docs.python.org/3/library/stdtypes.html#memoryview
+    Read more about Python's
+    [`memoryview` here](https://docs.python.org/3/library/stdtypes.html#memoryview).
     """
 
     # WebSocket ready state constants.
@@ -180,15 +177,14 @@ def handle_message(event):
 
     def __init__(self, url, protocols=None, **handlers):
         """
-        Create a new WebSocket connection from the given `url` (ws:// or
-        wss://). Optionally specify `protocols` (a string or a list of
-        protocol strings) and event handlers (onopen, onmessage, etc.) as
+        Create a new WebSocket connection from the given `url` (`ws://` or
+        `wss://`). Optionally specify `protocols` (a string or a list of
+        protocol strings) and event handlers (`onopen`, `onmessage`, etc.) as
         keyword arguments.
 
-        These arguments and naming conventions mirror those of the underlying
-        JavaScript WebSocket API for familiarity.
-
-        https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+        These arguments and naming conventions mirror those of the
+        [underlying JavaScript WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+        for familiarity.
 
         If you need access to the underlying JavaScript WebSocket instance,
         you can get it via the `_js_websocket` attribute.
@@ -230,7 +226,7 @@ def __getattr__(self, attr):
         Get an attribute `attr` from the underlying WebSocket.
 
         This allows transparent access to WebSocket properties like
-        readyState, url, bufferedAmount, etc.
+        `readyState`, `url`, `bufferedAmount`, etc.
         """
         return getattr(self._js_websocket, attr)
 
@@ -238,7 +234,7 @@ def __setattr__(self, attr, value):
         """
         Set an attribute `attr` on the WebSocket to the given `value`.
 
-        Event handler attributes (onopen, onmessage, etc.) are specially
+        Event handler attributes (`onopen`, `onmessage`, etc.) are specially
         handled to create proper proxies. Other attributes are set on the
         underlying WebSocket directly.
         """
@@ -249,10 +245,10 @@ def __setattr__(self, attr, value):
 
     def send(self, data):
         """
-        Send data through the WebSocket.
+        Send `data` through the WebSocket.
 
-        Accepts both text (str) and binary data (bytes, bytearray, etc.).
-        Binary data is automatically converted to a JavaScript Uint8Array.
+        Accepts both text (`str`) and binary data (`bytes`, `bytearray`, etc.).
+        Binary data is automatically converted to a JavaScript `Uint8Array`.
 
         ```python
         # Send text.
@@ -263,7 +259,9 @@ def send(self, data):
         ws.send(bytearray([5, 6, 7, 8]))
         ```
 
-        The WebSocket **must be in the OPEN state to send data**.
+        !!! warning
+
+            The WebSocket **must be in the OPEN state to send data**.
         """
         if isinstance(data, str):
             self._js_websocket.send(data)
@@ -275,8 +273,8 @@ def send(self, data):
 
     def close(self, code=None, reason=None):
         """
-        Close the WebSocket connection. Optionally specify a `code` (integer)
-        and a `reason` (string) for closing the connection.
+        Close the WebSocket connection. Optionally specify a `code` (`int`)
+        and a `reason` (`str`) for closing the connection.
 
         ```python
         # Normal close.
@@ -286,9 +284,8 @@ def close(self, code=None, reason=None):
         ws.close(code=1000, reason="Task completed")
         ```
 
-        Usage and values for `code` and `reasons` are explained here:
-
-        https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close
+        Usage and values for `code` and `reasons`
+        [are explained here](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close).
         """
         if code and reason:
             self._js_websocket.close(code, reason)
diff --git a/pyscript/workers.py b/pyscript/workers.py
index 4a104ba..5e23732 100644
--- a/pyscript/workers.py
+++ b/pyscript/workers.py
@@ -1,8 +1,8 @@
 """
-Worker management for PyScript.
-
-This module provides access to named web workers defined in script tags, and
-utilities for dynamically creating workers from Python code.
+This module provides access to named
+[web workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
+defined in `<script>` tags, and utilities for dynamically creating workers
+from Python code.
 
 Named workers are Python web workers defined in HTML with a `name` attribute
 that can be referenced from the main thread or other workers. This module
@@ -49,11 +49,11 @@ def add(a, b):
 ```
 
 Key features:
-- Access (await) named workers via dictionary-like syntax.
+- Access (`await`) named workers via dictionary-like syntax.
 - Dynamically create workers from Python.
 - Cross-interpreter support (Pyodide and MicroPython).
 
-Worker access is asynchronous - you must await `workers[name]` to get
+Worker access is asynchronous - you must `await workers[name]` to get
 a reference to the worker. This is because workers may not be ready
 immediately at startup.
 """
@@ -66,7 +66,7 @@ def add(a, b):
 class _ReadOnlyWorkersProxy:
     """
     A read-only proxy for accessing named web workers. Use
-    create_named_worker() to create new workers found in this proxy.
+    `create_named_worker()` to create new workers found in this proxy.
 
     This provides dictionary-like access to named workers defined in
     the page. It handles differences between Pyodide and MicroPython
@@ -127,6 +127,7 @@ def __getattr__(self, name):
 
 # Global workers proxy for accessing named workers.
 workers = _ReadOnlyWorkersProxy()
+"""Global proxy for accessing named web workers."""
 
 
 async def create_named_worker(src, name, config=None, type="py"):
@@ -135,7 +136,7 @@ async def create_named_worker(src, name, config=None, type="py"):
     `name` and optional `config` (dict or JSON string) and `type` (`py`
     for Pyodide or `mpy` for MicroPython, the default is `py`).
 
-    This function creates a new web worker by injecting a script tag into
+    This function creates a new web worker by injecting a `<script>` tag into
     the document. The worker will be accessible via the `workers` proxy once
     it's ready.
 
@@ -169,8 +170,10 @@ async def create_named_worker(src, name, config=None, type="py"):
     )
     ```
 
-    **The worker script should define** `__export__` to specify which
-    functions or objects are accessible from the main thread.
+    !!! info
+    
+        **The worker script should define** `__export__` to specify which
+        functions or objects are accessible from the main thread.
     """
     # Create script element for the worker.
     script = js.document.createElement("script")

From f492bdbdeae3f888b80d7f96cdf845576df04a84 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Tue, 9 Dec 2025 06:21:15 +0000
Subject: [PATCH 7/8] Add symbol type indicators to the table of contents in
 the API documentation.

---
 mkdocs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index 2e0e698..280b6a3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -69,6 +69,7 @@ plugins:
             show_source: true
             members_order: source
             show_symbol_type_heading: true
+            show_symbol_type_toc: true
 
 nav:
   - Home: index.md

From 615bca93cbc3917e7a7d980e73eeacb866bf75f4 Mon Sep 17 00:00:00 2001
From: "Nicholas H.Tollervey" <ntoll@ntoll.org>
Date: Tue, 9 Dec 2025 06:57:43 +0000
Subject: [PATCH 8/8] Updated API source.

---
 pyscript/__init__.py  | 17 +++++++++--------
 pyscript/context.py   |  2 +-
 pyscript/events.py    | 10 +++++-----
 pyscript/fetch.py     |  8 +++-----
 pyscript/ffi.py       | 15 ++++++++-------
 pyscript/flatted.py   |  6 +++---
 pyscript/fs.py        | 10 +++++-----
 pyscript/media.py     | 10 +++++-----
 pyscript/storage.py   |  6 +++---
 pyscript/util.py      |  4 ++--
 pyscript/web.py       | 12 ++++++------
 pyscript/websocket.py |  4 ++--
 pyscript/workers.py   |  4 ++--
 13 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/pyscript/__init__.py b/pyscript/__init__.py
index ecae1e4..644ec56 100644
--- a/pyscript/__init__.py
+++ b/pyscript/__init__.py
@@ -1,7 +1,7 @@
 """
 This is the main `pyscript` namespace. It provides the primary Pythonic API
 for users to interact with the
-[browser's own API](https://developer.mozilla.org/en-US/docs/Web/API). It 
+[browser's own API](https://developer.mozilla.org/en-US/docs/Web/API). It
 includes utilities for common activities such as displaying content, handling
 events, fetching resources, managing local storage, and coordinating with
 web workers.
@@ -47,7 +47,7 @@
 
 
 !!! Note
-    Some notes about the naming conventions and the relationship between 
+    Some notes about the naming conventions and the relationship between
     various similar-but-different names found within this code base.
 
     ```python
@@ -63,17 +63,18 @@
     ```
 
     The `_pyscript` module is an internal API implemented in JS. **End users
-    should not use it directly**. For its implementation, grep for 
+    should not use it directly**. For its implementation, grep for
     `interpreter.registerJsModule("_pyscript",...)` in `core.js`.
 
     ```python
     import js
     ```
 
-    The `js` object is the JS `globalThis`, as exported by Pyodide and/or
-    Micropython's foreign function interface (FFI). As such, it contains
-    different things in the main thread or in a worker, as defined by web
-    standards.
+    The `js` object is
+    [the JS `globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis),
+    as exported by Pyodide and/or Micropython's foreign function interface
+    (FFI). As such, it contains different things in the main thread or in a
+    worker, as defined by web standards.
 
     ```python
     import pyscript.context
@@ -85,7 +86,7 @@
     mostly for internal PyScript use or advanced users. In particular, it
     defines `window` and `document` in such a way that these names work in
     both cases: in the main thread, they are the "real" objects, in a worker
-    they are proxies which work thanks to 
+    they are proxies which work thanks to
     [coincident](https://github.com/WebReflection/coincident).
 
     ```python
diff --git a/pyscript/context.py b/pyscript/context.py
index c685047..b3f775c 100644
--- a/pyscript/context.py
+++ b/pyscript/context.py
@@ -3,7 +3,7 @@
 
 This module handles the differences between running in the
 [main browser thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread)
-versus running in a 
+versus running in a
 [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
 providing a consistent API regardless of the execution context.
 
diff --git a/pyscript/events.py b/pyscript/events.py
index dd4fd22..93fc03b 100644
--- a/pyscript/events.py
+++ b/pyscript/events.py
@@ -49,7 +49,7 @@ def __init__(self):
 
     def trigger(self, result):
         """
-        Trigger the event and notify all listeners with the given result.
+        Trigger the event and notify all listeners with the given `result`.
         """
         for listener in self._listeners:
             if is_awaitable(listener):
@@ -61,7 +61,7 @@ def add_listener(self, listener):
         """
         Add a function to be called when this event is triggered.
 
-        The listener must be callable. It can be either a regular function
+        The `listener` must be callable. It can be either a regular function
         or an async function. Duplicate listeners are ignored.
         """
         if not callable(listener):
@@ -72,7 +72,7 @@ def add_listener(self, listener):
 
     def remove_listener(self, *listeners):
         """
-        Remove specified listeners. If none specified, remove all listeners.
+        Remove specified `listeners`. If none specified, remove all listeners.
         """
         if listeners:
             for listener in listeners:
@@ -166,7 +166,7 @@ def decorator(func):
 
 def _get_elements(selector):
     """
-    Convert various selector types into a list of DOM elements.
+    Convert various `selector` types into a list of DOM elements.
     """
     from pyscript.web import Element, ElementCollection
 
@@ -184,7 +184,7 @@ def _get_elements(selector):
 
 def _create_wrapper(func):
     """
-    Create an appropriate wrapper for the given function.
+    Create an appropriate wrapper for the given function, `func`.
 
     The wrapper handles both sync and async functions, and respects whether
     the function expects to receive event arguments.
diff --git a/pyscript/fetch.py b/pyscript/fetch.py
index 97de453..77cbf47 100644
--- a/pyscript/fetch.py
+++ b/pyscript/fetch.py
@@ -1,5 +1,5 @@
 """
-This module provides a Python-friendly interface to the 
+This module provides a Python-friendly interface to the
 [browser's fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API),
 returning native Python data types and supporting directly awaiting the promise
 and chaining method calls directly on the promise.
@@ -156,15 +156,13 @@ def fetch(url, **options):
 
     The function takes a `url` and optional fetch `options` as keyword
     arguments. The `options` correspond to the JavaScript fetch API's
-    RequestInit dictionary, and commonly include:
+    [RequestInit dictionary](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit),
+    and commonly include:
 
     - `method`: HTTP method (e.g., `"GET"`, `"POST"`, `"PUT"` etc.)
     - `headers`: Dict of request headers.
     - `body`: Request body (string, dict for JSON, etc.)
 
-    See [this documentation](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
-    for more details of these web standards.
-
     The function returns a promise that resolves to a Response-like object
     with Pythonic methods to extract data:
 
diff --git a/pyscript/ffi.py b/pyscript/ffi.py
index 2394862..30fd77d 100644
--- a/pyscript/ffi.py
+++ b/pyscript/ffi.py
@@ -1,8 +1,9 @@
 """
-This module provides a unified Foreign Function Interface (FFI) layer that
-works consistently across both Pyodide and MicroPython, and in worker or main
-thread contexts, abstracting away the differences in their JavaScript interop
-APIs.
+This module provides a unified
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface)
+layer for Python/JavaScript interactions, that works consistently across both
+Pyodide and MicroPython, and in a worker or main thread context, abstracting
+away the differences in their JavaScript interop APIs.
 
 The following utilities work on both the main thread and in worker contexts:
 
@@ -74,7 +75,7 @@ def to_js(value, **kw):
     """
     Convert Python objects to JavaScript objects.
 
-    This ensures a Python `dict` becomes a 
+    This ensures a Python `dict` becomes a
     [proper JavaScript object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
     rather a JavaScript [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map),
     which is more intuitive for most use cases.
@@ -86,7 +87,7 @@ def to_js(value, **kw):
     from pyscript import ffi
     import js
 
-    
+
     note = {
         "body": "This is a notification",
         "icon": "icon.png"
@@ -111,7 +112,7 @@ def is_none(value):
     from pyscript import ffi
     import js
 
-    
+
     val1 = None
     val2 = js.null
     val3 = 42
diff --git a/pyscript/flatted.py b/pyscript/flatted.py
index b001b36..a49568e 100644
--- a/pyscript/flatted.py
+++ b/pyscript/flatted.py
@@ -1,5 +1,5 @@
 """
-This module is a Python implementation of the 
+This module is a Python implementation of the
 [Flatted JavaScript library](https://www.npmjs.com/package/flatted), which
 provides a light and fast way to serialize and deserialize JSON structures
 that contain circular references.
@@ -157,7 +157,7 @@ def parse(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
-    
+
     # Parse a Flatted JSON string.
     json_string = '[{"name": "1", "self": "0"}, "parent"]'
     obj = flatted.parse(json_string)
@@ -202,7 +202,7 @@ def stringify(value, *args, **kwargs):
     ```python
     from pyscript import flatted
 
-    
+
     # Create an object with a circular reference.
     parent = {"name": "parent", "children": []}
     child = {"name": "child", "parent": parent}
diff --git a/pyscript/fs.py b/pyscript/fs.py
index ec31282..c6c87c4 100644
--- a/pyscript/fs.py
+++ b/pyscript/fs.py
@@ -5,7 +5,7 @@
 
 !!! warning
     **This API only works in Chromium-based browsers** (Chrome, Edge,
-    Opera, Brave, etc.) that support the 
+    Vivaldi, Brave, etc.) that support the
     [File System Access API](https://wicg.github.io/file-system-access/).
 
 The module maintains a `mounted` dictionary that tracks all currently mounted
@@ -78,7 +78,7 @@ async def mount(path, mode="readwrite", root="", id="pyscript"):
     ```python
     from pyscript import fs
 
-    
+
     # Basic mount with default settings.
     await fs.mount("/local")
 
@@ -162,7 +162,7 @@ async def sync(path):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local")
 
     # Make changes to files.
@@ -194,7 +194,7 @@ async def unmount(path):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local")
     # ... work with files ...
     await fs.unmount("/local")
@@ -227,7 +227,7 @@ async def revoke(path, id="pyscript"):
     ```python
     from pyscript import fs
 
-    
+
     await fs.mount("/local", id="my-app")
     # ... work with files ...
 
diff --git a/pyscript/media.py b/pyscript/media.py
index c541b14..e60a9bc 100644
--- a/pyscript/media.py
+++ b/pyscript/media.py
@@ -41,7 +41,7 @@ class Device:
     """
     Represents a media input or output device.
 
-    This class wraps a browser 
+    This class wraps a browser
     [MediaDeviceInfo object](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo),
     providing Pythonic access to device properties like `ID`, `label`, and
     `kind` (audio/video, input/output).
@@ -52,7 +52,7 @@ class Device:
     ```python
     from pyscript.media import list_devices
 
-    
+
     # Get all available devices.
     devices = await list_devices()
 
@@ -135,7 +135,7 @@ async def request_stream(cls, audio=False, video=True):
         from pyscript import document
         from pyscript.media import Device
 
-        
+
         # Get default video stream.
         stream = await Device.request_stream()
 
@@ -185,7 +185,7 @@ async def get_stream(self):
         ```python
         from pyscript.media import list_devices
 
-        
+
         # List all devices.
         devices = await list_devices()
 
@@ -219,7 +219,7 @@ async def list_devices():
     ```python
     from pyscript.media import list_devices
 
-    
+
     # Get all devices.
     devices = await list_devices()
 
diff --git a/pyscript/storage.py b/pyscript/storage.py
index ca2fe6c..50640a9 100644
--- a/pyscript/storage.py
+++ b/pyscript/storage.py
@@ -109,7 +109,7 @@ class Storage(dict):
     ```python
     from pyscript import storage
 
-    
+
     # Open a storage.
     prefs = await storage("preferences")
 
@@ -130,7 +130,7 @@ class Storage(dict):
     ```python
     from pyscript import storage, Storage, window
 
-    
+
     class LoggingStorage(Storage):
         def __setitem__(self, key, value):
             window.console.log(f"Setting {key} = {value}")
@@ -220,7 +220,7 @@ async def storage(name="", storage_class=Storage):
     ```python
     from pyscript import storage
 
-    
+
     # Basic usage.
     user_data = await storage("user-profile")
     user_data["name"] = "Alice"
diff --git a/pyscript/util.py b/pyscript/util.py
index 4f45dcb..1b1b361 100644
--- a/pyscript/util.py
+++ b/pyscript/util.py
@@ -56,8 +56,8 @@ def is_awaitable(obj):
     """
     Returns a boolean indication if the passed in obj is an awaitable
     function. This is interpreter agnostic.
-    
-    !!! info 
+
+    !!! info
         MicroPython treats awaitables as generator functions, and if
         the object is a closure containing an async function or a bound method
         we need to work carefully.
diff --git a/pyscript/web.py b/pyscript/web.py
index 4b93261..af46408 100644
--- a/pyscript/web.py
+++ b/pyscript/web.py
@@ -270,7 +270,7 @@ class Element:
 
         Some elements have an underscore suffix in their class names (e.g.
         `select_`, `input_`).
-        
+
         This is to avoid clashes with Python keywords. The underscore is removed
         when determining the actual HTML tag name.
 
@@ -280,7 +280,7 @@ class Element:
     # Find and wrap an element by CSS selector.
     existing = web.page.find(".my_class")[0]
 
-    # Or, better, just use direct ID lookup (with or without the 
+    # Or, better, just use direct ID lookup (with or without the
     # leading '#').
     existing = web.page["my-element"]
     ```
@@ -396,7 +396,7 @@ def handle_click(event):
     !!! warning
         **Some HTML attributes clash with Python keywords and use trailing
         underscores**.
-    
+
     Use `for_` instead of `for`, and `class_` instead of `class`.
 
     ```python
@@ -675,7 +675,7 @@ def clone(self, clone_id=None):
 
     def find(self, selector):
         """
-        Find all descendant elements matching the 
+        Find all descendant elements matching the
         [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
         Returns an `ElementCollection` (possibly empty).
@@ -1122,7 +1122,7 @@ def elements(self):
 
     def find(self, selector):
         """
-        Find all descendants matching the 
+        Find all descendants matching the
         [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
         Searches within all elements in the collection.
@@ -1157,7 +1157,7 @@ def update_all(self, **kwargs):
 
 class canvas(ContainerElement):
     """
-    A bespoke 
+    A bespoke
     [HTML canvas element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas)
     with Pythonic drawing and download capabilities.
     """
diff --git a/pyscript/websocket.py b/pyscript/websocket.py
index 9fbd227..da735d1 100644
--- a/pyscript/websocket.py
+++ b/pyscript/websocket.py
@@ -14,7 +14,7 @@
 - Naming deliberately follows the JavaScript WebSocket API closely for
   familiarity.
 
-See the Python docs for 
+See the Python docs for
 [an explanation of memoryview](https://docs.python.org/3/library/stdtypes.html#memoryview).
 
 
@@ -123,7 +123,7 @@ class WebSocket:
 
     Access the underlying WebSocket methods and properties directly if needed.
     However, the wrapper provides a more Pythonic API. If you need to work
-    with the raw JavaScript WebSocket instance, you can access it via the 
+    with the raw JavaScript WebSocket instance, you can access it via the
     `_js_websocket` attribute.
 
     Using textual (`str`) data:
diff --git a/pyscript/workers.py b/pyscript/workers.py
index 5e23732..bdaf29b 100644
--- a/pyscript/workers.py
+++ b/pyscript/workers.py
@@ -140,7 +140,7 @@ async def create_named_worker(src, name, config=None, type="py"):
     the document. The worker will be accessible via the `workers` proxy once
     it's ready.
 
-    It return a promise that resolves to the worker reference when ready.
+    It returns a promise that resolves to the worker reference when ready.
 
     ```python
     from pyscript import create_named_worker
@@ -171,7 +171,7 @@ async def create_named_worker(src, name, config=None, type="py"):
     ```
 
     !!! info
-    
+
         **The worker script should define** `__export__` to specify which
         functions or objects are accessible from the main thread.
     """