Index of every page on this site: llms.txt
All skills
wado-lang avatar
by Wadowado-lang/wado121 stars
2
Run it yourself

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.

  • 1 file
  • 10.9 KB
  • Updated 6 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/wado-lang/wado/jco

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈41 tokens for metadata: the name and description. ≈2.7k when used: this file.

Description uses 2.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈165 characters, or 2.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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-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/:

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(...) 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at b208ba0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 days ago

README badge

README badge for wado-lang/wado/jco