WebAssembly: compile a script into a module
shotcup:wasm compiles a script in your sandbox into a WebAssembly module that runs outside Shotcup: in Node, in Deno, or in a bundler's build. The module carries its own runtime and calls nothing on Shotcup; it is a file the run writes, like a PNG or a PDF, and you host it. Compiling happens inside a run and counts like any other run. The module needs no engine switch.
import { compile } from "shotcup:wasm";
const result = compile("/main.ts");
console.log(result.wasmBytes, result.exports);Not every program compiles yet. When a compile meets something it does not compile, it stops with an Error whose message starts with wasm: and names the feature, and writes nothing. What does not compile yet lists them, and the table shows the language features and built-ins one by one.
compile(entry, { out })
compile(entry, options) reads the sandbox file entry (a path such as "/main.ts"; a relative path starts from /), parses it with the run's language profile and with its type annotations checked at run time (every compile does), and writes the module.
out(optional) names the.wasmfile, under/out/, its name made of letters, digits,_,-and.. The default is/out/app.wasm.- It returns
{ wasm, companion, wasmBytes, companionBytes, functions, exports }: the two paths, their sizes in bytes, the number of functions compiled, andexports, a list of{ name, kind }whosekindis"function"or"constant". - An option other than
out, or anoutthat is not such a path, is aTypeError. A missing entry is anError. A cap below is aRangeErrornaming it.
Your script's exports are the module's: functions, async functions (which return promises), generators, and constants that are numbers, strings, booleans, null or undefined.
Your own files
An import of another script file in your sandbox, by a relative or absolute path (import { total } from "./lib.ts"), is compiled into the same module. Each file runs once, as the module loads, after the files it imports and in the order JavaScript runs modules, and an imported binding stays live: when the file that exports it writes it again, the importer reads the new value. The entry's exports are the module's, and the entry can re-export another file's (export { run } from "./impl.ts", export * from "./lib.ts"): each is then an export like the entry's own, a function with its own name and length. Another file's exports that the entry does not re-export are seen only by the files that import them.
Not compiled yet: an import cycle between your files, a namespace import of one (import * as lib from "./lib.ts"), and an import of a file that is not a script, such as JSON, YAML or text.
The files it writes
| File | What it is |
|---|---|
<name>.wasm | The module. |
<name>.companion.js | A small JavaScript module the .wasm imports by its relative name. Keep it beside the module. |
A module that passes objects, arrays or functions to and from its host also writes <name>.proof.js and <name>.preload.js, and the result names them as proof and preload with their sizes. Keep proof.js beside the companion; preload.js is optional (below). The files come back with the run like any other file it writes under /out, as downloads.
Limits per plan
Every plan has shotcup:wasm. The caps apply to one compile call:
| Plan | Each source file | Functions | Output (the files together) |
|---|---|---|---|
| Free | 24 KiB | 2,000 | 1 MiB |
| Pro | 192 KiB | 20,000 | 8 MiB |
| Scale | 192 KiB | 50,000 | 16 MiB |
| Platform | 192 KiB | 50,000 | 16 MiB |
The source cap applies to each file the compile reads: the entry and each of your files it imports. The functions cap counts the functions of all of them. A compile also needs memory from the run's heap, in proportion to the size of those files together. It checks before it compiles each file, and a program that does not fit is a RangeError before the module is built. The files it writes count against the sandbox's storage like any other file.
Load the module
// Node 24.15 or later
const app = await import("./app.wasm");
console.log(app.total([1, 2, 3]));A bare import in your script (fs, node:fs, a package name) stays an import of the module, and the host resolves it when it loads the module, as it would for JavaScript. Shotcup's own modules (shotcup:canvas, shotcup:html and the others) exist only in a run, so the compile refuses an import of one.
A module has exactly the capabilities of the host modules its script imports. Import fs and it reads and writes the host's files; import a module that starts processes or runs code from text, and so can it. The compile does not limit what an import can do: check what you import, as you would for any JavaScript you run. The same goes for what your own code hands the module, such as the arguments of an exported function: it uses what it is given.
Beyond that, a module reaches the host's built-ins through String, RegExp, Math, Boolean, Number and the values they give. It cannot build a function from text through them: the Function constructor it can reach that way throws the same TypeError it throws on Shotcup.
When your script names a property of String, RegExp, Math, Boolean or Number, it can read only the members they have on Shotcup. Any other member, an assignment to or delete of one, and __proto__ and its relatives stop the compile with a wasm: error, or throw a TypeError whose message starts with wasm:. A host method your script calls behaves as it does in JavaScript, including any change it makes: an array's push called on Math, for example, adds an element to it, as it does on Shotcup.
If you load the preload, load it first, before any code that replaces a built-in, and once in each realm:
await import("./app.preload.js");
const app = await import("./app.wasm");It lets the module take faster paths through host objects and arrays. Without it the module uses the ordinary methods, which is the safe default.
JSON.parse and JSON.stringify are the module's own, with the same results and error messages as on Shotcup. When they read an object or array that came from the host, they use the host's Object.keys, Array.isArray and a few other built-ins as they were when the module loaded. If the host replaces one of them later, the module's JSON does not change. What JSON.parse returns works in template literals, +, arithmetic and comparisons, as in JavaScript, except an object or array whose own toString, valueOf or join is a function: the compile stops at one of your script's functions there, and a function from the host there is a TypeError whose message starts with wasm: when the conversion would call it.
console is the host's. console.log and the other methods a script has on Shotcup (info, debug, warn, error, dir, table, assert, count, countReset, time, timeLog, timeEnd, group, groupEnd, clear and trace) call the host's console, so the text is the host's: how it shows objects and arrays, whether it reads format strings such as %s, which stream each method writes to, and the Warning:, Error:, Info: and Debug: that Shotcup's console puts before those methods' lines and the host's does not. Plain strings and numbers print the same. Objects and arrays reach the console as copies made at the call: a getter runs to fill the copy, and an instance shows no class name, as on Shotcup. An error that leaves the module carries only its name and message as its stack, with no lines naming the module's code.
Reading a property by a key your script makes as it runs (table[name]) works on your script's own objects and arrays, as in JavaScript: properties it inherits, getters, array elements and length, and undefined for a key nothing holds. A key that names a built-in method the module does not compile, such as toString or __proto__ on a plain object, throws a TypeError whose message starts with wasm:. Such a read of a value that may also be a string, a number or a host value, such as one JSON.parse returned, does not compile yet.
Where it runs
A module needs WebAssembly 3.0's exception references and the JavaScript string built-ins, and a host that loads a .wasm file through import():
| Host | Loads the module |
|---|---|
| Node | 24.15 or later (it prints an experimental warning) |
| Deno | 2.3.2 or later |
| Vite | 8.2 or later |
| webpack | with asyncWebAssembly; its string built-ins are not checked |
| Browsers | not yet: no release browser loads a .wasm file through import() |
| Bun | not through import() yet |
Language features and built-ins
Each row is a small program compiled and run under Node and Bun, its result compared with the same script run on Shotcup. "Compiled" means the module does it itself. "Calls the host" means the module calls the host's own built-in or module for it, so it behaves as the host's does: the String methods, Math, RegExp and turning numbers into text come from the host.
| Language | Status |
|---|---|
| Numbers, arithmetic and bitwise operators | Compiled |
| Strings and template literals | Compiled |
| Numbers as text (String(n), a number in a template) | Calls the host |
| let, const and block scope | Compiled |
| Destructuring and spread | Compiled |
| Closures | Compiled |
| Default and rest parameters | Compiled |
| Arguments past the declared parameters | Compiled |
| Objects, computed keys and getters and setters | Compiled |
| Optional chaining and nullish coalescing | Compiled |
| typeof, instanceof, in and delete | Compiled |
| Classes, fields, inheritance and super | Compiled |
| Static members and static blocks | Compiled |
| Private fields and methods | Not compiled yet |
| Exceptions: try, catch, finally and throw | Compiled |
| Labelled break and continue, switch | Compiled |
| Iterators, for...of and Symbol.iterator | Compiled |
| Generators | Compiled |
| async functions and await | Compiled |
| Async generators and for await | Compiled |
| A top-level await | Not compiled yet |
| Regular expression literals | Calls the host |
| Tagged templates | Not compiled yet |
| BigInt | Not compiled yet |
| Decorators | Not compiled yet |
| Enums | Not compiled yet |
| using and await using | Not compiled yet |
| JSX | Compiled |
| Imports of the program's own files | Compiled |
| Import cycles between the program's own files | Not compiled yet |
| Namespace imports of the program's own files | Not compiled yet |
| Shotcup's own modules (shotcup:canvas, shotcup:html and the others) | Not compiled yet |
| Bare imports (provided by the host) | Calls the host |
| export default of an expression | Not compiled yet |
| Built-in | Status |
|---|---|
| Math | Calls the host |
| String methods | Calls the host |
| RegExp objects and their methods | Calls the host |
| Number | Calls the host |
| Number.prototype.toFixed | Not compiled yet |
| Boolean | Calls the host |
| Array methods | Compiled |
| Array static methods (Array.from, Array.isArray) | Compiled |
| Object static methods (Object.keys, Object.entries) | Compiled |
| JSON.stringify (a replacer, an indent, toJSON) | Compiled |
| JSON.parse (a reviver) | Compiled |
| JSON.rawJSON and JSON.isRawJSON | Not compiled yet |
| Map | Compiled |
| Set | Compiled |
| WeakMap and WeakSet | Not compiled yet |
| Promise | Compiled |
| Symbol() | Not compiled yet |
| Error and its subclasses | Compiled |
| Date | Not compiled yet |
| Temporal | Not compiled yet |
| Intl | Not compiled yet |
| console | Calls the host |
| globalThis | Not compiled yet |
| Proxy and Reflect | Not compiled yet |
| ArrayBuffer and typed arrays | Not compiled yet |
| TextEncoder and TextDecoder | Not compiled yet |
What does not compile yet
We compile every one of our run templates, and the language tests of GocciaScript, the engine Shotcup runs, that run in Shotcup's default language profile. Each module that compiles runs under Node and Bun, and its results must equal the same script run on the engine. A template counts as compiled only when its module, run under Node and Bun with the template's files, prints and writes exactly what the template's own run on Shotcup does.
- Templates: 29. 2 compile and give the same results; 27 stop at a compile error that names the feature.
- GocciaScript's language tests: 933 files, of which 838 run in Shotcup's default profile. 282 compile, and their 1,207 tests give the same results as on the engine; 548 stop at a compile error that names the feature; 2 the engine does not parse in that profile either; 6 compile and differ where a value crosses between the module and its host.
Mocking your own files, such as a test runner's vi.mock of one of them, is not supported: they are compiled in as they are, so a mock the compile does not catch has no effect.
Each row is what the compile says, and how many templates and test files stop there first. A file stops at its first, so a feature further down the same file is not counted; a row without a count comes from the table above.
| The compile says | Templates | Language test files |
|---|---|---|
| the import of "shotcup:canvas" is refused: shotcup:canvas has no host outside Shotcup | 7 | |
| the import of "shotcup:zip" is refused: shotcup:zip has no host outside Shotcup | 3 | |
| import() of a computed specifier (opcode OP_COMPUTED_IMPORT_SPECIFIER is not compiled yet) | 2 | 7 |
| converting a compiled object to a string is not compiled yet | 2 | 1 |
| the global Date is not compiled yet | 2 | 1 |
| a file larger than the plan's maxWasmSourceBytes | 2 | |
| a top-level await is not compiled yet | 1 | 21 |
| Number.prototype.toFixed is not compiled yet | 1 | 1 |
| a call of a value of more than one type is not compiled yet | 1 | |
| a namespace-only or side-effect import of "goccia:yaml" is not compiled yet | 1 | |
| opcode OP_CREATE_ARGUMENTS is not compiled yet | 1 | |
| opcode OP_SET_PROP_CONST_LOOSE is not compiled yet | 1 | |
| the import of "shotcup:html" is refused: shotcup:html has no host outside Shotcup | 1 | |
| the import of "shotcup:result" is refused: shotcup:result has no host outside Shotcup | 1 | |
| the import of "shotcup:streams" is refused: shotcup:streams has no host outside Shotcup | 1 | |
| the global globalThis is not compiled yet | 35 | |
| an import of a file that is not a script ("./…") is not compiled yet | 27 | |
| an import cycle is not compiled yet | 26 | |
| a class whose parent is not a class written in the same code that the transform can follow is not compiled yet | 24 | |
| the global Goccia is not compiled yet | 24 | |
| decorators (opcode OP_BEGIN_DECORATORS is not compiled yet) | 22 | |
| a private name (a private field) is not compiled yet | 20 | |
| a BigInt is not compiled yet | 19 | |
| an async function or a generator passed to the host is not compiled yet | 17 | |
| a global name the program reads without declaring it is not compiled yet | 16 | |
| export default of an expression is not compiled yet; declare it (const x = ...) and export { x as default } | 16 | |
| Symbol() is not compiled yet | 15 | |
| a using or await using declaration is not compiled yet | 15 | |
| enums (opcode OP_FINALIZE_ENUM is not compiled yet) | 12 | |
| import() (opcode OP_DYNAMIC_IMPORT is not compiled yet) | 12 | |
| the property constructor, which Object.prototype or an error may give, is not compiled yet | 12 | |
| a private name (OP_CLASS_DECLARE_PRIVATE_STATIC_CONST) is not compiled yet | 11 | |
an export that a function assigns (an exported let that changes after the module loads), which is not compiled yet | 11 | |
| enums (opcode OP_ENUM_KEYS is not compiled yet) | 11 | |
| OP_ADD on a value of more than one type is not compiled yet | 9 | |
| the property name of a function is not compiled yet | 9 | |
| getters and setters with computed names (opcode OP_DEFINE_ACCESSOR_DYNAMIC is not compiled yet) | 8 | |
| iterating a value of more than one type is not compiled yet | 8 | |
| assigning a global (opcode OP_SET_GLOBAL is not compiled yet) | 7 | |
| delete of a computed property (opcode OP_DEL_INDEX is not compiled yet) | 7 | |
| import.meta (opcode OP_IMPORT_META is not compiled yet) | 7 | |
| a tagged template is not compiled yet | 5 | |
| pattern matching (opcode OP_MATCH_HAS_PROPERTY is not compiled yet) | 5 | |
| the global ArrayBuffer is not compiled yet | 5 | |
| import defer (opcode OP_IMPORT_DEFER is not compiled yet) | 4 | |
| module mocking of the program's own files is not compiled yet | 4 | |
| the global Proxy is not compiled yet | 4 | |
| the property call of a function is not compiled yet | 4 | |
| OP_GET_THIS_BINDING in a function is not compiled yet | 3 | |
| a host namespace value is not compiled yet | 3 | |
| a namespace import of "./…", one of the program's own files, is not compiled yet | 3 | |
| pattern matching (opcode OP_MATCH_VALUE is not compiled yet) | 3 | |
| Array.prototype.slice is not compiled yet | 2 | |
| Array.prototype.sort is not compiled yet | 2 | |
| OP_ADD on an object is not compiled yet | 2 | |
| OP_LT on an object is not compiled yet | 2 | |
| OP_MUL on a value of more than one type is not compiled yet | 2 | |
| a class that extends Map is not compiled yet | 2 | |
| a computed property key that may be a string is not compiled yet | 2 | |
| a property key that may be an object is not compiled yet | 2 | |
| an import of "./…" with attributes is not compiled yet | 2 | |
| instanceof with the global Object or Array is not compiled yet | 2 | |
| new of a value of more than one type is not compiled yet | 2 | |
| new.target (opcode OP_NEW_TARGET is not compiled yet) | 2 | |
| the property apply of a function is not compiled yet | 2 | |
| the property hasOwnProperty, which Object.prototype or an error may give, is not compiled yet | 2 | |
| the property length of a function is not compiled yet | 2 | |
| typeof the global Object or Array is not compiled yet | 2 | |
| < on an object is not compiled yet | 1 | |
| Array.prototype.Symbol(Symbol.iterator) is not compiled yet | 1 | |
| Number.prototype.toString is not compiled yet | 1 | |
| OP_BXOR on a function is not compiled yet | 1 | |
| OP_DIV on a function is not compiled yet | 1 | |
| OP_DIV on an object is not compiled yet | 1 | |
| OP_INC_NUMERIC on a value of more than one type is not compiled yet | 1 | |
| OP_INC_NUMERIC on an object is not compiled yet | 1 | |
| OP_POW on an object is not compiled yet | 1 | |
| Object.defineProperty of a function is not compiled yet | 1 | |
| Object.defineProperty of a value of more than one type is not compiled yet | 1 | |
| Object.defineProperty of the realm's prototype is not compiled yet | 1 | |
| Object.getOwnPropertyDescriptor of a value of more than one type is not compiled yet | 1 | |
| Object.getOwnPropertyNames is not compiled yet | 1 | |
| Object.getPrototypeOf of a value the analysis cannot follow is not compiled yet | 1 | |
| Symbol.hasInstance is not compiled yet | 1 | |
| Symbol.metadata is not compiled yet | 1 | |
| Symbol.toPrimitive is not compiled yet | 1 | |
| a comparison with a number on an object is not compiled yet | 1 | |
| a computed property key that may be a number is not compiled yet | 1 | |
| a function with properties of its own passed to the host is not compiled yet | 1 | |
| a namespace-only or side-effect import of "goccia:csv" is not compiled yet | 1 | |
| a namespace-only or side-effect import of "goccia:test" is not compiled yet | 1 | |
| a property descriptor on a value of more than one type is not compiled yet | 1 | |
| a write of the property length of a string is not compiled yet | 1 | |
| a write of the property missing of a number is not compiled yet | 1 | |
| an error message that may be an object is not compiled yet (ToPrimitive) | 1 | |
| an index of a function is not compiled yet | 1 | |
| an instruction with more than 300 operands (a call's arguments, a closure's captured bindings) is not compiled yet | 1 | |
| in on a number is not compiled yet | 1 | |
| new of a function that is not a class is not compiled yet | 1 | |
| spreading a string into an object is not compiled yet | 1 | |
| super property reads outside a class method (opcode OP_SUPER_BASE is not compiled yet) | 1 | |
| super property reads outside a class method (opcode OP_SUPER_GET is not compiled yet) | 1 | |
| the element "0" of an array by a string key is not compiled yet | 1 | |
| the export default is not one function, which is not compiled yet | 1 | |
| the global Float64Array is not compiled yet | 1 | |
| the global Reflect is not compiled yet | 1 | |
| the property bind of a function is not compiled yet | 1 | |
| the property stack, which Object.prototype or an error may give, is not compiled yet | 1 | |
| the property toString, which Object.prototype or an error may give, is not compiled yet | 1 | |
| the re-export namespaceExport (from "./…") is not compiled yet | 1 | |
| JSON.rawJSON is not compiled yet | ||
| the global Intl is not compiled yet | ||
| the global Temporal is not compiled yet | ||
| the global TextEncoder is not compiled yet | ||
| the global Uint8Array is not compiled yet | ||
| the global WeakMap is not compiled yet |
Cold start
The time from nothing loaded to a module ready to call, for the parts of four templates that compile today, each measured in 21 fresh processes: the median, with the 10th and 90th percentiles. On Node it is import() of the module, which reads it and its companion, compiles, links and instantiates it. Bun does not load a .wasm file through import(), so there it is WebAssembly.instantiate with the companion and the string built-ins supplied in JavaScript. Measured on 6 November 2026 on a desktop with an AMD Ryzen AI Max+ 395, Linux x86-64, Node 24.21.0, Bun 1.4.2.
| Program | Module and companion | Node | Bun |
|---|---|---|---|
| browser-planner's walk of an accessibility tree | 84 KiB | 2.8 ms (2.7 ms–5.8 ms) | 4.5 ms (4.2 ms–5.2 ms) |
| the code-mode-orchestrator's tool filters and totals | 37 KiB | 2.6 ms (2.5 ms–6.3 ms) | 3.8 ms (3.6 ms–4.5 ms) |
| fetch-diff-monitor's release normaliser | 36 KiB | 3.1 ms (3.0 ms–6.5 ms) | 3.8 ms (3.6 ms–4.5 ms) |
| hook-policy's rules and its decision function | 108 KiB | 3.2 ms (3.1 ms–3.6 ms) | 4.9 ms (4.7 ms–5.9 ms) |
This page as Markdown: /docs/wasm.md