Skip to content

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.

JavaScript
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 .wasm file, 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, and exports, a list of { name, kind } whose kind is "function" or "constant".
  • An option other than out, or an out that is not such a path, is a TypeError. A missing entry is an Error. A cap below is a RangeError naming 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

FileWhat it is
<name>.wasmThe module.
<name>.companion.jsA 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:

PlanEach source fileFunctionsOutput (the files together)
Free24 KiB2,0001 MiB
Pro192 KiB20,0008 MiB
Scale192 KiB50,00016 MiB
Platform192 KiB50,00016 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

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

JavaScript
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():

HostLoads the module
Node24.15 or later (it prints an experimental warning)
Deno2.3.2 or later
Vite8.2 or later
webpackwith asyncWebAssembly; its string built-ins are not checked
Browsersnot yet: no release browser loads a .wasm file through import()
Bunnot 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.

LanguageStatus
Numbers, arithmetic and bitwise operatorsCompiled
Strings and template literalsCompiled
Numbers as text (String(n), a number in a template)Calls the host
let, const and block scopeCompiled
Destructuring and spreadCompiled
ClosuresCompiled
Default and rest parametersCompiled
Arguments past the declared parametersCompiled
Objects, computed keys and getters and settersCompiled
Optional chaining and nullish coalescingCompiled
typeof, instanceof, in and deleteCompiled
Classes, fields, inheritance and superCompiled
Static members and static blocksCompiled
Private fields and methodsNot compiled yet
Exceptions: try, catch, finally and throwCompiled
Labelled break and continue, switchCompiled
Iterators, for...of and Symbol.iteratorCompiled
GeneratorsCompiled
async functions and awaitCompiled
Async generators and for awaitCompiled
A top-level awaitNot compiled yet
Regular expression literalsCalls the host
Tagged templatesNot compiled yet
BigIntNot compiled yet
DecoratorsNot compiled yet
EnumsNot compiled yet
using and await usingNot compiled yet
JSXCompiled
Imports of the program's own filesCompiled
Import cycles between the program's own filesNot compiled yet
Namespace imports of the program's own filesNot 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 expressionNot compiled yet
Built-inStatus
MathCalls the host
String methodsCalls the host
RegExp objects and their methodsCalls the host
NumberCalls the host
Number.prototype.toFixedNot compiled yet
BooleanCalls the host
Array methodsCompiled
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.isRawJSONNot compiled yet
MapCompiled
SetCompiled
WeakMap and WeakSetNot compiled yet
PromiseCompiled
Symbol()Not compiled yet
Error and its subclassesCompiled
DateNot compiled yet
TemporalNot compiled yet
IntlNot compiled yet
consoleCalls the host
globalThisNot compiled yet
Proxy and ReflectNot compiled yet
ArrayBuffer and typed arraysNot compiled yet
TextEncoder and TextDecoderNot 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 saysTemplatesLanguage test files
the import of "shotcup:canvas" is refused: shotcup:canvas has no host outside Shotcup7
the import of "shotcup:zip" is refused: shotcup:zip has no host outside Shotcup3
import() of a computed specifier (opcode OP_COMPUTED_IMPORT_SPECIFIER is not compiled yet)27
converting a compiled object to a string is not compiled yet21
the global Date is not compiled yet21
a file larger than the plan's maxWasmSourceBytes2
a top-level await is not compiled yet121
Number.prototype.toFixed is not compiled yet11
a call of a value of more than one type is not compiled yet1
a namespace-only or side-effect import of "goccia:yaml" is not compiled yet1
opcode OP_CREATE_ARGUMENTS is not compiled yet1
opcode OP_SET_PROP_CONST_LOOSE is not compiled yet1
the import of "shotcup:html" is refused: shotcup:html has no host outside Shotcup1
the import of "shotcup:result" is refused: shotcup:result has no host outside Shotcup1
the import of "shotcup:streams" is refused: shotcup:streams has no host outside Shotcup1
the global globalThis is not compiled yet35
an import of a file that is not a script ("./…") is not compiled yet27
an import cycle is not compiled yet26
a class whose parent is not a class written in the same code that the transform can follow is not compiled yet24
the global Goccia is not compiled yet24
decorators (opcode OP_BEGIN_DECORATORS is not compiled yet)22
a private name (a private field) is not compiled yet20
a BigInt is not compiled yet19
an async function or a generator passed to the host is not compiled yet17
a global name the program reads without declaring it is not compiled yet16
export default of an expression is not compiled yet; declare it (const x = ...) and export { x as default }16
Symbol() is not compiled yet15
a using or await using declaration is not compiled yet15
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 yet12
a private name (OP_CLASS_DECLARE_PRIVATE_STATIC_CONST) is not compiled yet11
an export that a function assigns (an exported let that changes after the module loads), which is not compiled yet11
enums (opcode OP_ENUM_KEYS is not compiled yet)11
OP_ADD on a value of more than one type is not compiled yet9
the property name of a function is not compiled yet9
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 yet8
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 yet5
pattern matching (opcode OP_MATCH_HAS_PROPERTY is not compiled yet)5
the global ArrayBuffer is not compiled yet5
import defer (opcode OP_IMPORT_DEFER is not compiled yet)4
module mocking of the program's own files is not compiled yet4
the global Proxy is not compiled yet4
the property call of a function is not compiled yet4
OP_GET_THIS_BINDING in a function is not compiled yet3
a host namespace value is not compiled yet3
a namespace import of "./…", one of the program's own files, is not compiled yet3
pattern matching (opcode OP_MATCH_VALUE is not compiled yet)3
Array.prototype.slice is not compiled yet2
Array.prototype.sort is not compiled yet2
OP_ADD on an object is not compiled yet2
OP_LT on an object is not compiled yet2
OP_MUL on a value of more than one type is not compiled yet2
a class that extends Map is not compiled yet2
a computed property key that may be a string is not compiled yet2
a property key that may be an object is not compiled yet2
an import of "./…" with attributes is not compiled yet2
instanceof with the global Object or Array is not compiled yet2
new of a value of more than one type is not compiled yet2
new.target (opcode OP_NEW_TARGET is not compiled yet)2
the property apply of a function is not compiled yet2
the property hasOwnProperty, which Object.prototype or an error may give, is not compiled yet2
the property length of a function is not compiled yet2
typeof the global Object or Array is not compiled yet2
< on an object is not compiled yet1
Array.prototype.Symbol(Symbol.iterator) is not compiled yet1
Number.prototype.toString is not compiled yet1
OP_BXOR on a function is not compiled yet1
OP_DIV on a function is not compiled yet1
OP_DIV on an object is not compiled yet1
OP_INC_NUMERIC on a value of more than one type is not compiled yet1
OP_INC_NUMERIC on an object is not compiled yet1
OP_POW on an object is not compiled yet1
Object.defineProperty of a function is not compiled yet1
Object.defineProperty of a value of more than one type is not compiled yet1
Object.defineProperty of the realm's prototype is not compiled yet1
Object.getOwnPropertyDescriptor of a value of more than one type is not compiled yet1
Object.getOwnPropertyNames is not compiled yet1
Object.getPrototypeOf of a value the analysis cannot follow is not compiled yet1
Symbol.hasInstance is not compiled yet1
Symbol.metadata is not compiled yet1
Symbol.toPrimitive is not compiled yet1
a comparison with a number on an object is not compiled yet1
a computed property key that may be a number is not compiled yet1
a function with properties of its own passed to the host is not compiled yet1
a namespace-only or side-effect import of "goccia:csv" is not compiled yet1
a namespace-only or side-effect import of "goccia:test" is not compiled yet1
a property descriptor on a value of more than one type is not compiled yet1
a write of the property length of a string is not compiled yet1
a write of the property missing of a number is not compiled yet1
an error message that may be an object is not compiled yet (ToPrimitive)1
an index of a function is not compiled yet1
an instruction with more than 300 operands (a call's arguments, a closure's captured bindings) is not compiled yet1
in on a number is not compiled yet1
new of a function that is not a class is not compiled yet1
spreading a string into an object is not compiled yet1
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 yet1
the export default is not one function, which is not compiled yet1
the global Float64Array is not compiled yet1
the global Reflect is not compiled yet1
the property bind of a function is not compiled yet1
the property stack, which Object.prototype or an error may give, is not compiled yet1
the property toString, which Object.prototype or an error may give, is not compiled yet1
the re-export namespaceExport (from "./…") is not compiled yet1
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.

ProgramModule and companionNodeBun
browser-planner's walk of an accessibility tree84 KiB2.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 totals37 KiB2.6 ms (2.5 ms–6.3 ms)3.8 ms (3.6 ms–4.5 ms)
fetch-diff-monitor's release normaliser36 KiB3.1 ms (3.0 ms–6.5 ms)3.8 ms (3.6 ms–4.5 ms)
hook-policy's rules and its decision function108 KiB3.2 ms (3.1 ms–3.6 ms)4.9 ms (4.7 ms–5.9 ms)

This page as Markdown: /docs/wasm.md