#let myplugin = plugin("hello.wasm")\n#let concat(a, b) = str(\n myplugin.concatenate(\n bytes(a),\n bytes(b),\n )\n)\n\n#concat("hello", "world")\n![\"Preview\"](\"/en-US-v0.13.1/assets/563eb9b72603c710f73876546a243de1.png\")
Loads a WebAssembly module.
\nThe resulting module will contain one Typst function for each function\nexport of the loaded WebAssembly module.
\nTypst WebAssembly plugins need to follow a specific\nprotocol. To run as a plugin, a program needs to be\ncompiled to a 32-bit shared WebAssembly library. Plugin functions may accept\nmultiple byte buffers as arguments and return a single byte\nbuffer. They should typically be wrapped in idiomatic Typst functions that\nperform the necessary conversions between native Typst types and bytes.
\nFor security reasons, plugins run in isolation from your system. This means\nthat printing, reading files, or similar things are not supported.
\n#let myplugin = plugin("hello.wasm")\n#let concat(a, b) = str(\n myplugin.concatenate(\n bytes(a),\n bytes(b),\n )\n)\n\n#concat("hello", "world")\nSince the plugin function returns a module, it can be used with import\nsyntax:
\n#import plugin("hello.wasm"): concatenate\nPlugin functions must be pure: A plugin function call most not have any\nobservable side effects on future plugin calls and given the same arguments,\nit must always return the same value.
\nThe reason for this is that Typst functions must be pure (which is quite\nfundamental to the language design) and, since Typst function can call\nplugin functions, this requirement is inherited. In particular, if a plugin\nfunction is called twice with the same arguments, Typst might cache the\nresults and call your function only once. Moreover, Typst may run multiple\ninstances of your plugin in multiple threads, with no state shared between\nthem.
\nTypst does not enforce plugin function purity (for efficiency reasons), but\ncalling an impure function will lead to unpredictable and irreproducible\nresults and must be avoided.
\nThat said, mutable operations can be useful for plugins that require\ncostly runtime initialization. Due to the purity requirement, such\ninitialization cannot be performed through a normal function call. Instead,\nTypst exposes a plugin transition API, which executes\na function call and then creates a derived module with new functions which\nwill observe the side effects produced by the transition call. The original\nplugin remains unaffected.
\nAny Typst code can make use of a plugin simply by including a WebAssembly\nfile and loading it. However, because the byte-based plugin interface is\nquite low-level, plugins are typically exposed through a package containing\nthe plugin and idiomatic wrapper functions.
\nMany compilers will use the WASI ABI by default or as\ntheir only option (e.g. emscripten), which allows printing, reading files,\netc. This ABI will not directly work with Typst. You will either need to\ncompile to a different target or stub all\nfunctions.
\nTo be used as a plugin, a WebAssembly module must conform to the following\nprotocol:
\nA plugin module can export functions to make them callable from Typst. To\nconform to the protocol, an exported function should:
\nTake n 32-bit integer arguments a_1, a_2, ..., a_n (interpreted as\nlengths, so usize/size_t may be preferable), and return one 32-bit\ninteger.
The function should first allocate a buffer buf of length a_1 + a_2 + ... + a_n, and then call\nwasm_minimal_protocol_write_args_to_buffer(buf.ptr).
The a_1 first bytes of the buffer now constitute the first argument, the\na_2 next bytes the second argument, and so on.
The function can now do its job with the arguments and produce an output\nbuffer. Before returning, it should call\nwasm_minimal_protocol_send_result_to_host to send its result back to the\nhost.
To signal success, the function should return 0.
To signal an error, the function should return 1. The written buffer is\nthen interpreted as an UTF-8 encoded error message.
Plugin modules need to import two functions that are provided by the\nruntime. (Types and functions are described using WAT syntax.)
\n(import "typst_env" "wasm_minimal_protocol_write_args_to_buffer" (func (param i32)))
Writes the arguments for the current function into a plugin-allocated\nbuffer. When a plugin function is called, it receives the\nlengths of its input buffers as arguments. It should then\nallocate a buffer whose capacity is at least the sum of these lengths. It\nshould then call this function with a ptr to the buffer to fill it with\nthe arguments, one after another.
(import "typst_env" "wasm_minimal_protocol_send_result_to_host" (func (param i32 i32)))
Sends the output of the current function to the host (Typst). The first\nparameter shall be a pointer to a buffer (ptr), while the second is the\nlength of that buffer (len). The memory pointed at by ptr can be freed\nimmediately after this function returns. If the message should be\ninterpreted as an error message, it should be encoded as UTF-8.
For more resources, check out the wasm-minimal-protocol\nrepository. It\ncontains:
\nA path to a WebAssembly file or raw WebAssembly bytes.
","example":null,"types":["str","bytes"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["module"],"scope":[{"path":["plugin"],"name":"transition","title":"Transition","keywords":[],"oneliner":"Calls a plugin function that has side effects and returns a new module","element":false,"contextual":false,"deprecation":null,"details":"Calls a plugin function that has side effects and returns a new module\nwith plugin functions that are guaranteed to have observed the results\nof the mutable call.
\nNote that calling an impure function through a normal function call\n(without use of the transition API) is forbidden and leads to\nunpredictable behaviour. Read the section on purity\nfor more details.
\nIn the example below, we load the plugin hello-mut.wasm which exports\ntwo functions: The get() function retrieves a global array as a\nstring. The add(value) function adds a value to the global array.
We call add via the transition API. The call mutated.get() on the\nderived module will observe the addition. Meanwhile the original module\nremains untouched as demonstrated by the base.get() call.
Note: Due to limitations in the internal WebAssembly implementation,\nthe transition API can only guarantee to reflect changes in the plugin's\nmemory, not in WebAssembly globals. If your plugin relies on changes to\nglobals being visible after transition, you might want to avoid use of\nthe transition API for now. We hope to lift this limitation in the\nfuture.
","example":"#let base = plugin("hello-mut.wasm")\n#assert.eq(base.get(), "[]")\n\n#let mutated = plugin.transition(base.add, "hello")\n#assert.eq(base.get(), "[]")\n#assert.eq(mutated.get(), "[hello]")\nThe plugin function to call.
","example":null,"types":["function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"arguments","details":"The byte buffers to call the function with.
","example":null,"types":["bytes"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":true,"settable":false}],"returns":["module"],"scope":[]}]}}}