browser: pyfun bundle, a Dom façade in the cookbook, and the Promise-to-Async note

[simontreanor]

Closes #111, the last of the fourth dogfooding session's nine issues (ROADMAP item 20).

pyfun bundle

pyfun bundle <entry.pyfun> -o <dir> [--asset <file>]... [--page <fragment.html>]

A static page that runs the program: index.html, the compiled Python (one main.py, or a project's whole .py tree), the assets, and pyfun-bundle.js, a module script that boots Pyodide from its CDN (the release the playground pins), stages the files into the in-browser file system, and runs the entry with stdout and stderr in two <pre> panes. --page puts the program's own markup above them. A type error stops the bundle before anything is written. The program is then a shareable link with no server, which is how two players get a game whose interface is the browser.

The Dom façade (cookbook)

examples/interop/browser/dom.pyfun is the first real consumer of the "publish a façade, import many" axis: extern import js, opaque Element/Event/Callback, instance-access externs for the methods (.replaceChildren(), .addEventListener()), and Pyodide's create_proxy behind Dom.proxy, so the lifetime detail lives in the façade, not the program. counter.pyfun is the consumer: a top-level let mut the click handler reassigns (a global in the emitted Python), and the handler is an ordinary one-parameter function that Python calls with the event, which is the calling convention #107 settled on. Emitted:

import dom
count = 0
def render(_):
    return dom.setText(dom.byId("count"), f"{count}")
def bump(_):
    global count
    count = count + 1
    return render(None)
dom.on(dom.byId("plus"), "click", dom.proxy(bump))
render(None)

The harness compile-checks the example as a project (tests/project.rs); running it needs a browser.

The Promise to Async bridge

Nothing to build: a JS promise is awaitable under Pyodide, so an extern over a JS async API is typed -> Async a and awaited with let! like any other. DESIGN.md §6 ("Browser target") records all three pieces; README gets the CLI line, the cookbook README the row, ROADMAP item 20 is closed.

Tests

tests/cli.rs: a project entry with an asset and a page fragment bundles to the expected files with the expected loader constants; a single file bundles as main.py; a type error writes nothing. tests/project.rs: the browser example type-checks and lowers with the expected shapes. cargo test, cargo clippy --all-targets and cargo fmt --check are clean.