wado-lang/wado / .claude/skills/jco
jco
VerifiedTranspile Wado Wasm components to JS with jco, then run, debug, and benchmark them on Node. Use for anything that involves jco, Node, or a browser as the host.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
SKILL.md
View on GitHub---
name: jco
description: Transpile Wado Wasm components to JS with jco, then run, debug, and benchmark them on Node. Use for anything that involves jco, Node, or a browser as the host.
---
# Running Wado on Node via jco
jco (bytecodealliance) transpiles a Wasm **component** into JS + core Wasm so it
runs on a plain Wasm engine (V8/Node, browsers) instead of a Component Model
runtime. Wado targets WASI P3; this doc covers what the released jco does for
Wado today and what is still blocked.
## TL;DR
- Use the **released npm jco as a library** (`scripts/jco`, `mise run jco-*`).
- Compile Wado with **`-f no-wide-arithmetic`** — V8 has no wide-arithmetic
proposal, and float formatting / `i128` emit it.
- Run on **Node 26+** — stable JSPI, no flag.
- **Compute and filesystem programs work** (including float formatting). A
filesystem program needs its preopen set with `_setPreopens` (see below).
- Quick check: `mise run jco-hello-released`. Benchmark:
`mise run jco-bench <program.wado>`.
## Environment
- **Node 26+ required.** Node 26 (V8 14.6) ships **stable JSPI**
(`WebAssembly.Suspending`), so no flag is needed; the repo pins `node = "26"`
in `mise.toml`. Node 24 needs `--experimental-wasm-jspi`; Node 22's older JSPI
fails (`WebAssembly.Suspending` is not a constructor).
- **`/tmp` pitfall:** outside the repo, `node` may resolve to a system Node 22
(mise activation is path-scoped). Run inside the repo, or use the pinned
binary's absolute path.
- **V8 has no wide-arithmetic** in any version (no flag exists). This is a V8
gap, not a jco one — handled by `-f no-wide-arithmetic` (see below).
## Vendor-free pipeline (`scripts/jco`)
Released `@bytecodealliance/jco` as a library. `transpile-released.mjs` is a
plain `transpile()` — jco's own `preview3-shim` serves every import a Wado
program makes, and the output links to it through a `node_modules` symlink the
script writes beside the files.
A component whose main module imports from `"extern"` (a `wado-lang:web`
program) is transpiled a second time in jco's `instantiation` mode, as
`<name>.component.js`, and `<name>.js` becomes a loader: it instantiates the
core modules itself, puts `package-web/glue/*.js` (copied beside it as
`web-*.js`) in place of the trapping `extern` imports, and exports what the
plain transpile would.
`mise run test-web-glue` runs two such programs against jsdom.
The shim writes stdout from a worker that is torn down once the event loop
empties, so lines still queued when `run()` resolves are lost, and a runner that
calls `process.exit` on that promise loses more. Hold the loop open for a
second after `run()` resolves. The lines of one run can also arrive out of
order.
A program that reads files needs a preopen. Set it before importing the
transpiled module, mapping the guest's `.` to a host directory as
`wado run --dir <dir>::.` does:
```js
import { _setPreopens } from "@bytecodealliance/preview3-shim/filesystem";
_setPreopens({ ".": "/abs/host/dir" });
const m = await import("./out/prog.js");
await m.run.run();
await new Promise((r) => setTimeout(r, 1000));
```
Import the shim the output links to through its `node_modules` symlink. A
second copy of the shim holds its own preopen table, which the program never
reads.
mise tasks:
```sh
mise run jco-deps # npm install released jco under scripts/jco
mise run jco-transpile-released foo.wasm [out-dir]
mise run jco-hello-released # compile + transpile + run hello on Node
mise run jco-bench <program.wado> [runs] # compile -f no-wide-arithmetic, transpile, self-time
```
### Released jco status (verified at 1.30.0)
| Capability | Status |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Transpile (GC component) | ✅ works, `wasi:http/service` included |
| JSPI | ✅ native (Node 26 no flag; Node 24 needs the flag) |
| Wide-arithmetic component | ❌ `transpile` rejects it (`wide arithmetic support is not enabled`); even if forced, V8 rejects the opcode at runtime → use `-f no-wide-arithmetic` |
| Stdout via stream | ✅ jco's own shim delivers it, if the runner holds the event loop open after `run()` resolves |
| Filesystem read stream | ✅ reads through a preopen set with `_setPreopens` (zlib benchmark verified) |
## wide-arithmetic (`-f no-wide-arithmetic`)
Wado emits the Wasm wide-arithmetic proposal (`i64.mul_wide_u/s`, `i64.add128`,
`i64.sub128`) for float formatting (`core:prelude/fpfmt.wado`) and `i128`. **No
V8 implements it** (checked through Node 26; no flag, `--wasm-staging` no help),
so any component containing those opcodes fails `WebAssembly.compile` with
`invalid numeric opcode: 0xfc16`.
`-f no-wide-arithmetic` rewrites each such builtin call, before NIR, to a
32-bit-limb software form in `core:rt` (`i64_mul_wide_u_soft` and so on;
`wado-compiler/src/lower/wide_arith.rs`). NIR and WIR then show ordinary calls,
which the optimizer inlines. **Compile every Node-bound Wado program with this
flag** — a bare `println` of a float needs it.
## WASI shims
BA ships a `preview3-shim` implementing P3 `cli` / `clocks` / `filesystem` /
`http`, with a browser build beside the Node one. A plain `jco transpile` wires
it, and stdout, float formatting, `wasi:random`, `MonotonicClock` and an HTTP
`handle` all run through it unaided. Its **browser** `cli` is unimplemented
(`throw new Todo()`), which is why the playground keeps a hand-written one.
A hand-written clock is where precision goes missing: `system-clock.now` is an
instant carrying sub-second nanoseconds, and `get-resolution` a bare duration.
## Benchmarking on Node
`mise run jco-bench <program.wado> [runs]` compiles with `-f no-wide-arithmetic`,
transpiles via the released pipeline, and runs the program self-timed `runs`
times (default 3; keep the best). The benchmark programs already self-time via
`core:benchmark` + `MonotonicClock` and print their own
throughput line, so no host timing is needed.
`JCO_PREOPEN` names the host directory granted as the program's `.` (default:
the repository root). The benchmarks read their data relative to `benchmark/`:
```sh
mise run jco-bench benchmark/mandelbrot/mandelbrot.wado
JCO_PREOPEN=benchmark mise run jco-bench benchmark/zlib/zlib_bench.wado
```
| Benchmark | Wado on Node (jco) | Wado on wasmtime |
| --------------- | ------------------ | ----------------------- |
| mandelbrot | ~4.0 M px/s | ~4.2 M |
| sieve | ~150 M numbers/s | ~64 M (V8 ~2.3× faster) |
| fts | ~12 M conv/s | — |
| zlib compress | ~65 MB/s | — |
| zlib decompress | ~220 MB/s | — |
The Node column is `mise run jco-bench <program.wado>` as above; the wasmtime
column is `wado run -O2 <program.wado>` from `benchmark/`, as
`benchmark/mise.toml` runs it.
Compute throughput on V8 lands within ~5–10% of wasmtime (sieve is much faster
on V8). Numbers are indicative on a noisy cloud VM; keep best-of-3.
The other filesystem benchmarks (json-{twitter,canada,catalog}, sqlite-parse,
syntax-highlight, cbor) load their data the same way, outside the timed loop,
but have not been run on Node yet.
## Known blockers (jco / V8 gaps)
### wide-arithmetic (V8)
Not jco. Handled by `-f no-wide-arithmetic`.
### Reusing an instance (jco)
An instance serves a couple of calls, then the next suspends on a stream read
whose host injection is never driven (`JCO_DEBUG=1` ends at
`[StreamEnd#copy()] blocked`). `cloudflare-worker/` builds one per request.
## Debugging jco runtime errors
Transpiled output is one large JS file. Useful canonical-builtin → JS mappings:
| Wasm builtin | jco JS function | Notes |
| --------------------- | ---------------------------------------------------- | ----------------- |
| `stream.write` | `streamWrite()` | JSPI Suspending |
| `stream.read` | `streamRead()` | JSPI Suspending |
| `canon lower (async)` | `_lowerImportBackwardsCompat()` | JSPI Suspending |
| `task.return` | `taskReturn()` | |
| `future.new` (lift) | `_genStreamHostInjectFn` / `createReadableStreamEnd` | host→guest wiring |
### Techniques
- **Catch swallowed errors** — jco's async machinery loses errors as unhandled
rejections:
```js
process.on('unhandledRejection', e => { console.error('UNHANDLED:', e); process.exit(1); });
```
- **`JCO_DEBUG=1 node run.mjs`** — verbose trace of every instruction/trampoline.
A trailing `[ComponentAsyncState#suspendTask()]` with no progress = a
rendezvous deadlock.
- **Inject logging** by string-replacing a function header in the transpiled JS
(e.g. add `console.error(...)` to `streamRead`/`generatedStreamHostInject`).
- **Timeout hangs**: `timeout 12 node run.mjs` so a deadlock doesn't wedge.
### Common error patterns
| Error | Likely cause |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `invalid numeric opcode: 0xfc16` | Wide-arithmetic — recompile with `-f no-wide-arithmetic` |
| `WebAssembly.Suspending is not a constructor` | Node < 24, or Node 22 picked up outside the repo (use Node 26) |
| `FutureReadableEnd is not defined` | Future-end classes not injected (run via `transpile-released.mjs`) |
| stdout empty or missing lines | The runner exits or empties the event loop before the shim's worker flushes (wait after `run()`) |
| Bare `unreachable` from a program that reads files | No preopen set (`_setPreopens`), or a path outside it; the panic message is lost with the exit |
| `wide arithmetic support is not enabled` (transpile) | Compile with `-f no-wide-arithmetic`; V8 cannot run the opcodes either |
| Hang / timeout | JSPI Suspending missing on a trampoline, or a stream rendezvous deadlock |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |