wasmhost 0.0.1a1__tar.gz

wasmhost-0.0.1a1/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"

wasmhost-0.0.1a1/.github/workflows/pre-commit.yml

@@ -0,0 +1,83 @@
+name: Pre-commit
+
+# Same flow as tiny-bclibc-wasm's: run every hook; on a pull request from this repo, commit what the
+# auto-fixing hooks (ruff) changed and verify again; anywhere else, changed files are a failure.
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: pre-commit-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  pre-commit:
+    name: pre-commit run --all-files
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools_scm needs tags for the package version
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          python-version: "3.11"
+
+      - name: Install pre-commit
+        run: uv tool install pre-commit
+
+      - name: Run pre-commit
+        id: first_run
+        continue-on-error: true
+        run: pre-commit run --all-files --show-diff-on-failure
+
+      - name: Check for changes
+        id: diff
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Fail (no auto-fixable changes, but hooks failed)
+        if: steps.diff.outputs.changed == 'false' && steps.first_run.outcome == 'failure'
+        run: exit 1
+
+      - name: Fail (changes produced, but not on a pull_request)
+        if: steps.diff.outputs.changed == 'true' && github.event_name != 'pull_request'
+        run: |
+          echo "pre-commit modified files, but auto-commit only runs on pull_request events."
+          git status --porcelain
+          exit 1
+
+      - name: Re-run pre-commit after auto-fixes
+        id: verify_run
+        if: steps.diff.outputs.changed == 'true' && github.event_name == 'pull_request'
+        continue-on-error: true
+        run: pre-commit run --all-files --show-diff-on-failure
+
+      - name: Fail (issues remain after auto-fix)
+        if: steps.diff.outputs.changed == 'true' && github.event_name == 'pull_request' && steps.verify_run.outcome == 'failure'
+        run: exit 1
+
+      - name: Commit and push auto-fixes
+        if: steps.diff.outputs.changed == 'true' && github.event_name == 'pull_request' && steps.verify_run.outcome == 'success'
+        env:
+          # through the environment, not inlined: a branch name is attacker-controlled text
+          BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "style: auto-fix via pre-commit"
+          git push origin "HEAD:$BRANCH"

wasmhost-0.0.1a1/.github/workflows/publish.yml

@@ -0,0 +1,110 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Publish to TestPyPI"
+        required: false
+        type: boolean
+        default: false
+      version:
+        description: "Override version (e.g. 0.1.0rc1); TestPyPI needs one without a dev/local suffix"
+        required: false
+        type: string
+        default: ""
+
+run-name: >
+  Publish → ${{ github.event_name == 'push' && 'PyPI' ||
+      inputs.testpypi && 'TestPyPI' || 'build only' }}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools_scm needs tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+
+      - name: Build (the wheel is built from the sdist, so this proves the sdist builds on its own)
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ inputs.version }}
+          # PyPI/TestPyPI reject local version segments (+g<hash>); keep them on build-only runs.
+          SETUPTOOLS_SCM_OVERRIDES_FOR_WASMHOST: >-
+            ${{ (github.event_name == 'push' || inputs.testpypi) && '{local_scheme = "no-local-version"}' || '' }}
+        run: uv build --out-dir dist
+
+      - name: Smoke-test the wheel in a clean environment
+        run: |
+          uv venv -q /tmp/smoke
+          uv pip install -q --python /tmp/smoke dist/*.whl
+          cd /tmp && WASMHOST_BACKEND=node /tmp/smoke/bin/python -c "
+          import wasmhost as wh
+          wasm = bytes.fromhex('0061736d0100000001070160027f7f017f03020100070701036164640000' '0a09010700200020016a0b')
+          assert wh.instantiate(wasm).instance.exports.add(2, 3) == 5
+          print('ok on', wh.get_backend().name)
+          "
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist
+          retention-days: 14
+
+  publish:
+    needs: build
+    if: github.event_name == 'push' || inputs.testpypi
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'push' && 'pypi' || 'testpypi' }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          repository-url: https://test.pypi.org/legacy/
+
+  release:
+    needs: build
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+
+      - name: Create GitHub release (draft)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --repo "${{ github.repository }}" \
+            --title "wasmhost ${{ github.ref_name }}" \
+            --generate-notes \
+            --draft \
+            artifacts/dist/*

wasmhost-0.0.1a1/.github/workflows/tests.yml

@@ -0,0 +1,105 @@
+name: Tests
+
+# Builds the package from source and runs the suite once per backend, selected with pytest's --wasm-backend
+# (see tests/conftest.py; a backend that can't start fails the step, it is never skipped). Coverage is not
+# collected here: tiny-bclibc-wasm runs the same backends through wasmhost and combines it there.
+#
+#   test:     every OS x CPython oldest/newest (also free-threaded 3.14t) + PyPy, on wasmtime and on Node (both
+#             available on every runner), and on wasm3 where pywasm3 installs (CPython 3.11+; built from git).
+#   jsc:      WebKitGTK's JavaScriptCore -- the engine behind Pythonista's JSContext -- with its JIT
+#             and without it (iOS apps like Pythonista run it without), as the stand-in for an iOS
+#             device.
+
+on:
+  push:
+    paths-ignore: &non-code-paths
+      - "**.md"
+      - "LICENSE"
+  pull_request:
+    paths-ignore: *non-code-paths
+  workflow_dispatch:
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.14", "3.14t", "pypy3.11"]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # setuptools_scm needs tags for the package version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: uv sync --locked
+
+      - name: pytest --wasm-backend wasmtime
+        run: uv run --locked pytest -v --wasm-backend wasmtime
+
+      - name: pytest --wasm-backend node
+        if: ${{ !cancelled() }} # run every backend even if an earlier one failed
+        run: uv run --locked pytest -v --wasm-backend node
+
+      - name: pytest --wasm-backend wasm3
+        # pywasm3 is a dev dependency only on CPython >= 3.11 (see pyproject.toml). Warnings are errors so
+        # that, on 3.14t, an extension turning the GIL back on at import fails the run.
+        if: ${{ !cancelled() && matrix.python-version != '3.10' && !startsWith(matrix.python-version, 'pypy') }}
+        run: uv run --locked pytest -v -W error::RuntimeWarning --wasm-backend wasm3
+
+      - name: Example
+        run: WASMHOST_BACKEND=node uv run --locked python examples/basic.py
+
+  jsc:
+    name: WebKitGTK JavaScriptCore
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install JavaScriptCore + PyGObject
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y -q gir1.2-javascriptcoregtk-4.1 python3-gi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4
+
+      # python3-gi is built for the distribution's own Python, so use that interpreter with its
+      # site-packages visible.
+      - name: Install into a system-site-packages venv
+        run: |
+          uv venv --system-site-packages --python /usr/bin/python3 .venv
+          uv pip install -e . pytest
+
+      - name: pytest --wasm-backend gi-jsc (JIT on)
+        run: .venv/bin/python -m pytest -v --wasm-backend gi-jsc
+        env:
+          JSC_useJIT: "true"
+
+      - name: pytest --wasm-backend gi-jsc (JIT off, as on iOS)
+        if: ${{ !cancelled() }}
+        run: .venv/bin/python -m pytest -v --wasm-backend gi-jsc
+        env:
+          JSC_useJIT: "false"
+
+      - name: Example
+        run: WASMHOST_BACKEND=gi-jsc .venv/bin/python examples/basic.py

wasmhost-0.0.1a1/.gitignore

@@ -0,0 +1,17 @@
+**/__pycache__
+**/.ruff_cache/
+**/.pytest_cache/
+**/.idea
+**/*.egg-info
+**/.venv
+**/build
+**/dist
+.vscode
+
+# written by setuptools_scm at build time
+src/wasmhost/_version.py
+# coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/

wasmhost-0.0.1a1/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+default_install_hook_types: [pre-commit]
+default_language_version:
+  python: python3
+
+repos:
+  - repo: local
+    hooks:
+      - id: uv-lock
+        name: uv lock check
+        entry: uv
+        # --check only, not --upgrade: dependency bumps are Dependabot's job; --upgrade would re-resolve to
+        # whatever is newest on PyPI at run time and fail later pushes with no code change involved.
+        args: ["lock", "--check"]
+        language: system
+        pass_filenames: false
+        files: '^(pyproject\.toml|uv\.lock)$'
+
+      - id: uv-sync
+        name: uv sync before hooks
+        entry: uv
+        args: ["sync"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-pyright
+        name: pyright
+        entry: uv
+        args: ["run", "pyright"]
+        language: system
+        pass_filenames: false
+        files: '\.pyi?$'
+
+      - id: uv-ruff-check
+        name: ruff lint & fix
+        entry: uv
+        args: ["run", "ruff", "check", "--fix"]
+        language: system
+        pass_filenames: false
+        files: '\.pyi?$'
+
+      - id: uv-ruff-format
+        name: ruff format
+        entry: uv
+        args: ["run", "ruff", "format"]
+        language: system
+        pass_filenames: false
+        files: '\.pyi?$'
+
+      - id: uv-pytest
+        name: pytest
+        entry: uv
+        # A few seconds: every JavaScript host that starts here (Node, and gi-jsc with PyGObject).
+        args: ["run", "pytest", "-q"]
+        language: system
+        pass_filenames: false
+        files: '(\.py|pyproject\.toml)$'

wasmhost-0.0.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 o-murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wasmhost-0.0.1a1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: wasmhost
+Version: 0.0.1a1
+Summary: WebAssembly for CPython, PyPy and Pythonista, run in JavaScriptCore or Node, with the JavaScript WebAssembly API
+Author-email: o-murphy <thehelixpg@gmail.com>
+License-Expression: MIT
+Keywords: webassembly,wasm,javascriptcore,jscontext,pythonista,node
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: iOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: wasmtime
+Requires-Dist: wasmtime>=49.0.0; extra == "wasmtime"
+Dynamic: license-file
+
+# wasmhost
+
+WebAssembly from **CPython, PyPy and Pythonista**, with the JavaScript WebAssembly API. It runs in
+whichever JavaScript engine is available: JavaScriptCore's `JSContext` in Pythonista on iOS, WebKitGTK's
+JavaScriptCore on Linux, or Node. Plain Python, no dependencies, no C extension.
+
+```python
+import wasmhost
+
+module = wasmhost.Module(open("lib.wasm", "rb").read())  # WebAssembly.Module
+instance = wasmhost.Instance(module)  # WebAssembly.Instance
+print(instance.exports.add(2, 3))  # i32/i64 -> int, f32/f64 -> float
+instance.exports.memory.write(ptr, b"data")  # WebAssembly.Memory
+print(instance.exports.counter.value)  # WebAssembly.Global
+```
+
+See `examples/basic.py`.
+
+- **Types.** The JavaScript API can't tell a function's signature, and it matters (an `i64` argument must reach
+  JavaScript as a BigInt), so the binary's type, import, function, global and export sections are read in
+  Python. `Module.exports(module)` and `Module.imports(module)` describe a module with them.
+- **Errors** are the API's: `CompileError`, `LinkError` and `Trap` (`WebAssembly.RuntimeError`, which is also a
+  `RuntimeError`); an out-of-bounds memory access is an `IndexError`.
+- **Memory** is copied, not shared: `memory.read(offset, n)`, `memory.write(offset, data)`, `memory[a:b]`,
+  `memory.grow(pages)`.
+
+## Batches
+
+On a JavaScript engine every call into it has a fixed cost (a pipe to `node`, a bridged Objective-C call in
+Pythonista). A batch does several steps in one trip (on `wasmtime` and `wasm3`, in Python), and a step can use the results of the earlier ones:
+
+```python
+batch = instance.batch()
+ptr = batch.call(instance.exports.alloc, len(data))  # a Ref
+batch.write(instance.exports.memory, ptr, data)
+status = batch.call(instance.exports.run, ptr)
+batch.stop_if_nonzero(status)  # leave the rest out on an error status
+out = batch.read(instance.exports.memory, ptr, 16)
+batch.run()
+out.value  # bytes (`.done` says whether the step ran)
+```
+
+A failing step (a trap, an out-of-bounds access) raises from `run()`, after the earlier steps' results are set.
+Only `i32` results can be used in arithmetic (`ptr * 8`, `ptr + 4`).
+
+## Backends
+
+| Backend | Where | How it is detected |
+|---|---|---|
+| `jscontext` | iOS (Pythonista, PythonIDE) | JavaScriptCore's `JSContext` through `objc_util` (both apps have it), or through [`rubicon-objc`](https://github.com/beeware/rubicon-objc) where that is missing (checked only against a fake bridge, not on a device) |
+| `wasmtime` | anywhere with the `wasmtime` package | `import wasmtime` (`pip install wasmtime`) |
+| `wasm3` | CPython 3.11+ with [pywasm3](https://github.com/wasm3/pywasm3) | `import wasm3`; install it from git: `uv add "pywasm3 @ git+https://github.com/wasm3/pywasm3"` (its PyPI release predates the API used here) |
+| `gi-jsc` | Linux | WebKitGTK's JavaScriptCore through PyGObject (`apt install gir1.2-javascriptcoregtk-4.1 python3-gi`) |
+| `node` | anywhere with Node.js | `node` on `PATH` |
+
+With nothing configured, the first backend that starts wins, in the order shown. Each backend's constructor is its
+own probe: it fails when its runtime is missing. Choose one with `WASMHOST_BACKEND=<name>`,
+`wasmhost.set_backend("<name>")` or `Module(..., backend="<name>")`; `wasmhost.get_backend().name` says which is in
+use. `wasmhost.close()` closes the backends it started. (In WebAssembly's words the *host* is the embedder, the
+Python side that provides imports; what runs the module is the backend.)
+
+Not every backend can do everything (`backend.supports("memory.grow")` and `supports("table.length")` say):
+`wasm3` can't `Memory.grow` from Python (`NotImplementedError`; a module's own `memory.grow` works) and has no
+tables API.
+
+## Try it on a device
+
+The package carries a self-test, since nothing else can be run in Pythonista to see whether this works there:
+
+```python
+import wasmhost
+wasmhost.selftest()                 # or, from a shell: python -m wasmhost [--backend NAME] [--all]
+```
+
+It prints one line per check (the Objective-C bridge in use, `WebAssembly` and `BigInt` in the engine, calls,
+`i64`, memory, globals, traps, batches, the cost of a call), then `N/M passed`. If something fails, send the whole
+output. On a computer, `python -m wasmhost --all` runs it on every backend that starts.
+
+### Where it has been run
+
+| Where | Backend | Result | A call / a batch of 3 |
+|---|---|---|---|
+| Pythonista 3 (StaSh 0.7.5), Python 3.10.4, iPhone17,3 | `jscontext` (`objc_util`) | 23/23 | 53 / 97 us |
+| PythonIDE, Python 3.14.7, `ios-13.0-arm64-iphoneos` | `jscontext` (`objc_util`) | 23/23 | 37 / 76 us |
+| Linux, CPython 3.14t | `gi-jsc` | 23/23 | 34 / 78 us |
+| Linux, CPython 3.14t | `node` | 23/23 | 82 / 116 us |
+| Linux, CPython 3.14t | `wasmtime` | 18/18 | 69 / 233 us |
+| Linux, CPython 3.14t | `wasm3` | 18/18 | 4 / 46 us |
+| Linux, CPython 3.10 and PyPy 3.10 | `node` | 23/23 (and the test suite on 3.10) | |
+
+The times are one run of the self-test each, so read them as an order of magnitude. Not run on a device: the
+`rubicon-objc` bridge (both iOS apps above have `objc_util`, so it wasn't needed), and imports (see below).
+
+## Not yet
+
+- **Imports.** A module that imports host functions, memories, tables or globals can't be instantiated
+  (`NotImplementedError`). Python callbacks need a synchronous bridge: native for `wasmtime` and `wasm3`, a JavaScript function
+  made from Python for `gi-jsc`, an Objective-C block for `jscontext`, and for `node` a blocking read of the pipe.
+- **Tables** beyond their length, `v128` and reference types, multi-value results in a batch.
+
+## Test
+
+```bash
+uv run pytest                            # every backend that starts here
+uv run pytest --wasm-backend node        # one backend: it must start, or the run stops with an error
+uv run pytest --wasm-backend wasmtime    # or wasm3
+uv run pytest --wasm-backend gi-jsc      # needs PyGObject: run it with a system-site-packages venv (see the CI job)
+uv run pyright && uv run ruff check
+```

wasmhost-0.0.1a1/README.md

@@ -0,0 +1,109 @@
+# wasmhost
+
+WebAssembly from **CPython, PyPy and Pythonista**, with the JavaScript WebAssembly API. It runs in
+whichever JavaScript engine is available: JavaScriptCore's `JSContext` in Pythonista on iOS, WebKitGTK's
+JavaScriptCore on Linux, or Node. Plain Python, no dependencies, no C extension.
+
+```python
+import wasmhost
+
+module = wasmhost.Module(open("lib.wasm", "rb").read())  # WebAssembly.Module
+instance = wasmhost.Instance(module)  # WebAssembly.Instance
+print(instance.exports.add(2, 3))  # i32/i64 -> int, f32/f64 -> float
+instance.exports.memory.write(ptr, b"data")  # WebAssembly.Memory
+print(instance.exports.counter.value)  # WebAssembly.Global
+```
+
+See `examples/basic.py`.
+
+- **Types.** The JavaScript API can't tell a function's signature, and it matters (an `i64` argument must reach
+  JavaScript as a BigInt), so the binary's type, import, function, global and export sections are read in
+  Python. `Module.exports(module)` and `Module.imports(module)` describe a module with them.
+- **Errors** are the API's: `CompileError`, `LinkError` and `Trap` (`WebAssembly.RuntimeError`, which is also a
+  `RuntimeError`); an out-of-bounds memory access is an `IndexError`.
+- **Memory** is copied, not shared: `memory.read(offset, n)`, `memory.write(offset, data)`, `memory[a:b]`,
+  `memory.grow(pages)`.
+
+## Batches
+
+On a JavaScript engine every call into it has a fixed cost (a pipe to `node`, a bridged Objective-C call in
+Pythonista). A batch does several steps in one trip (on `wasmtime` and `wasm3`, in Python), and a step can use the results of the earlier ones:
+
+```python
+batch = instance.batch()
+ptr = batch.call(instance.exports.alloc, len(data))  # a Ref
+batch.write(instance.exports.memory, ptr, data)
+status = batch.call(instance.exports.run, ptr)
+batch.stop_if_nonzero(status)  # leave the rest out on an error status
+out = batch.read(instance.exports.memory, ptr, 16)
+batch.run()
+out.value  # bytes (`.done` says whether the step ran)
+```
+
+A failing step (a trap, an out-of-bounds access) raises from `run()`, after the earlier steps' results are set.
+Only `i32` results can be used in arithmetic (`ptr * 8`, `ptr + 4`).
+
+## Backends
+
+| Backend | Where | How it is detected |
+|---|---|---|
+| `jscontext` | iOS (Pythonista, PythonIDE) | JavaScriptCore's `JSContext` through `objc_util` (both apps have it), or through [`rubicon-objc`](https://github.com/beeware/rubicon-objc) where that is missing (checked only against a fake bridge, not on a device) |
+| `wasmtime` | anywhere with the `wasmtime` package | `import wasmtime` (`pip install wasmtime`) |
+| `wasm3` | CPython 3.11+ with [pywasm3](https://github.com/wasm3/pywasm3) | `import wasm3`; install it from git: `uv add "pywasm3 @ git+https://github.com/wasm3/pywasm3"` (its PyPI release predates the API used here) |
+| `gi-jsc` | Linux | WebKitGTK's JavaScriptCore through PyGObject (`apt install gir1.2-javascriptcoregtk-4.1 python3-gi`) |
+| `node` | anywhere with Node.js | `node` on `PATH` |
+
+With nothing configured, the first backend that starts wins, in the order shown. Each backend's constructor is its
+own probe: it fails when its runtime is missing. Choose one with `WASMHOST_BACKEND=<name>`,
+`wasmhost.set_backend("<name>")` or `Module(..., backend="<name>")`; `wasmhost.get_backend().name` says which is in
+use. `wasmhost.close()` closes the backends it started. (In WebAssembly's words the *host* is the embedder, the
+Python side that provides imports; what runs the module is the backend.)
+
+Not every backend can do everything (`backend.supports("memory.grow")` and `supports("table.length")` say):
+`wasm3` can't `Memory.grow` from Python (`NotImplementedError`; a module's own `memory.grow` works) and has no
+tables API.
+
+## Try it on a device
+
+The package carries a self-test, since nothing else can be run in Pythonista to see whether this works there:
+
+```python
+import wasmhost
+wasmhost.selftest()                 # or, from a shell: python -m wasmhost [--backend NAME] [--all]
+```
+
+It prints one line per check (the Objective-C bridge in use, `WebAssembly` and `BigInt` in the engine, calls,
+`i64`, memory, globals, traps, batches, the cost of a call), then `N/M passed`. If something fails, send the whole
+output. On a computer, `python -m wasmhost --all` runs it on every backend that starts.
+
+### Where it has been run
+
+| Where | Backend | Result | A call / a batch of 3 |
+|---|---|---|---|
+| Pythonista 3 (StaSh 0.7.5), Python 3.10.4, iPhone17,3 | `jscontext` (`objc_util`) | 23/23 | 53 / 97 us |
+| PythonIDE, Python 3.14.7, `ios-13.0-arm64-iphoneos` | `jscontext` (`objc_util`) | 23/23 | 37 / 76 us |
+| Linux, CPython 3.14t | `gi-jsc` | 23/23 | 34 / 78 us |
+| Linux, CPython 3.14t | `node` | 23/23 | 82 / 116 us |
+| Linux, CPython 3.14t | `wasmtime` | 18/18 | 69 / 233 us |
+| Linux, CPython 3.14t | `wasm3` | 18/18 | 4 / 46 us |
+| Linux, CPython 3.10 and PyPy 3.10 | `node` | 23/23 (and the test suite on 3.10) | |
+
+The times are one run of the self-test each, so read them as an order of magnitude. Not run on a device: the
+`rubicon-objc` bridge (both iOS apps above have `objc_util`, so it wasn't needed), and imports (see below).
+
+## Not yet
+
+- **Imports.** A module that imports host functions, memories, tables or globals can't be instantiated
+  (`NotImplementedError`). Python callbacks need a synchronous bridge: native for `wasmtime` and `wasm3`, a JavaScript function
+  made from Python for `gi-jsc`, an Objective-C block for `jscontext`, and for `node` a blocking read of the pipe.
+- **Tables** beyond their length, `v128` and reference types, multi-value results in a batch.
+
+## Test
+
+```bash
+uv run pytest                            # every backend that starts here
+uv run pytest --wasm-backend node        # one backend: it must start, or the run stops with an error
+uv run pytest --wasm-backend wasmtime    # or wasm3
+uv run pytest --wasm-backend gi-jsc      # needs PyGObject: run it with a system-site-packages venv (see the CI job)
+uv run pyright && uv run ruff check
+```