jco
Skill120 starsChanged todayMITView on GitHub
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.
- Installs packages
In this repository39 other files it gives its agents.
- AGENTS.mdAGENTS.md
- benchmark/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- package-gale/AGENTS.mdAGENTS.md
- package-grog/AGENTS.mdAGENTS.md
- package-jade/AGENTS.mdAGENTS.md
- package-loam/AGENTS.mdAGENTS.md
- package-re/AGENTS.mdAGENTS.md
- package-wadopoet/AGENTS.mdAGENTS.md
- wado-bundled-icu/AGENTS.mdAGENTS.md
- wado-cli/AGENTS.mdAGENTS.md
- wado-compiler/AGENTS.mdAGENTS.md
- wado-from-idl/AGENTS.mdAGENTS.md
- wado-host/AGENTS.mdAGENTS.md
- wado-lsp/AGENTS.mdAGENTS.md
- wado-manifest/AGENTS.mdAGENTS.md
- wado-run-pjrt/AGENTS.mdAGENTS.md
- wado-run-webgpu/AGENTS.mdAGENTS.md
- wado-vscode/AGENTS.mdAGENTS.md
- benchmarkSkill
- ci-timingSkill
- code-review-responseSkill
- coverage-investigationSkill
- crSkill
- debuggerSkill
- distillSkill
- eddySkill
- git-upstream-syncSkill
- markdownSkill
- on-task-doneSkill
- optimizer-debugSkill
- profiling-wado-compilerSkill
- pull-requestSkill
- rust-renameSkill
- rustSkill
- vendor-submodulesSkill
- wado-cliSkill
- wado-performanceSkill
- wasm-optSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Use the released npm jco as a library (scripts/jco, mise run jco-*).
- Distinctive: line 18
Run on Node 26+ — stable JSPI, no flag.
- Very specific: line 69
Import the shim the output links to through its node_modules symlink.
- Very specific: line 156
Not jco. Handled by -f no-wide-arithmetic.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 /i128emit 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 pinsnode = "26"inmise.toml. Node 24 needs--experimental-wasm-jspi; Node 22's older JSPI fails (WebAssembly.Suspendingis not a constructor). /tmppitfall: outside the repo,nodemay 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:
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:
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-timeReleased 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/:
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:
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(...)tostreamRead/generatedStreamHostInject). - Timeout hangs:
timeout 12 node run.mjsso 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 |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

