Module wasm::dom

wasm32 DOM and browser-API interop.

A wasm32-unknown-unknown module has no access to the page itself, so every browser operation here is an 'extern' js_* function that becomes a WebAssembly import (an undefined extern in a module linked with --allow-undefined is imported from "env"), implemented by the JS glue that ships beside this header: std/wasm/safec_dom.js. Load a module through it —

import { loadSafeC } from "./safec_dom.js";
const app = await loadSafeC(fetch("/app.wasm"));   // instantiates, wires every import
app.exports.start();

— and every dom_* function below works; see safec_dom.js's header for running under Node with a fake document (that is how the tests run it).

ABI. Strings go to JS as (pointer, length) into the module's linear memory and are read synchronously. Strings come back through a caller buffer: the import copies at most 'cap' bytes and returns the full length (-1 for "absent"), and the wrappers here retry with a buffer of that size, so the dom_* API hands out ordinary owned Strings. Elements are integer handles into a JS-side table (-1: none); DOM_DOCUMENT and DOM_WINDOW name the document and window. A handle stays valid until dom_release() — release elements you looked up or created in a loop, or the table grows for the page's lifetime.

Callbacks (events, timers, animation frames, fetch completions) are slots in one table of DOM_MAX_CALLBACKS entries; JS invokes them by id through the exported std_dom_dispatch_* functions. A handler receives its userdata (the generic ?&T it was registered with) and, for events, a DomEvent whose accessors read the event being dispatched — valid only during the handler. Every wrapper pairs fn void(?&T, ...) with ?&T, so the type-erased storage is always called correctly.

Memory: the strings these wrappers return are heap Strings; free them. (std/wasm/wasm_rt.sc's allocator is a bump allocator whose free() is a no-op — a long-running page should keep per-event allocation small.)