odin-web-sys

Import-only Web IDL bindings for stock Odin js_wasm32, in the spirit of Rust’s web-sys + a shared JS bridge (not a wasm-bindgen export product).

Piece	Role
bridge/	Hand-written JS runtime (runtime.js) + ABI.md (wire source of truth)
packages/	Git-tracked generated (and small hand) web:* packages
generator/	IDL → Odin (maintainers); apps only need packages + bridge
idl/	Pinned Web IDL + packages.json

Product decisions

1. Import only — no @(wasm_export) / pack product in this repo.
2. Audience — stock Odin js_wasm32 (no custom runtime language).
3. Bridge — hand-written JS; ABI rules live in bridge/ABI.md.
4. Packages — web: prefix, IDL-shaped grouping (Web IDL / WebRef).
5. Artifacts — generator output is git-tracked; check-gen fails on drift.
6. Async — promise_then always; JSPI promise_await when the host wraps promising exports.
7. Tree-shaking — reachable foreigns only (LLVM/Odin DCE); still split by IDL package.
8. Multi-return — js_wasm32 uses sret (see ABI.md).

App usage

odin build . -target:js_wasm32 -collection:web=path/to/odin-web-sys/packages

package main
import "web:dom"
// host loads bridge/runtime.js and supplies the import object

import { instantiate } from "./bridge/runtime.js";
const { instance } = await instantiate(await fetch("app.wasm"));
instance.exports._start?.();
instance.exports.start?.();

Maintainer commands

odin run build.odin -file                 # interactive menu
odin run build.odin -file -- generate
odin run build.odin -file -- update-idl
odin run build.odin -file -- check        # smoke + check-gen + probe
odin run build.odin -file -- demo         # WebGPU cube → :8765
odin run build.odin -file -- demo-scrollscape
odin run build.odin -file -- demo-console
odin run build.odin -file -- demo-jspi
odin run build.odin -file -- help

Static demos share one server:

odin run examples/server -file -- --port 8765 --demo /examples/webgpu_triangle
odin run examples/server -file -- --port 8766 --demo /examples/scrollscape

Layout

odin-web-sys/
  build.odin        # maintainer TUI / CI entry
  bridge/           # runtime.js + ABI.md
  packages/         # web:* (js hand-written; rest generated)
  generator/        # offline codegen
  webidl/           # vendored parser
  idl/              # pinned .idl + packages.json
  examples/         # demos + shared static server
  docs/             # STATUS, DECISIONS

Bridge (v0.5)

Feature	Support
Handle tagging	Heap objects index | 0x80000000; plain ints never look up as handles
Signed i32	Wasm i32 arrives signed in JS; Proxy coerceArg uses >>> 0
Proxy path	__web_* on web_bridge (dom, html, fetch, events, …)
Marshaller path	js_invoke_* + Odin js.inv_* — webgpu + console ("bridge" in idl/packages.json)
Strings	DOMString / USVString / ByteString (+ guest wasm_alloc)
Throws	clear_error / had_error + generated wrappers where needed
Callbacks	Return values, variadic, odin_web_sys_callback / _va
Promises	then / combinators + optional JSPI await
Buffers	Typed arrays, ArrayBuffer, copy helpers
Dictionaries	Builders with defaults + inherit

Full rules: bridge/ABI.md.

Status

Bridge v0.5.0 + core packages + demos (hello_console, webgpu_triangle, scrollscape, jspi_await).

See docs/STATUS.md and docs/DECISIONS.md.

License

TBD.