The client APIalpha

What are the calls, and how do page mode and worker mode differ?

moxzi/web/lib/moxzi.js is the layer between a page and the runtime, and its whole surface is async — even where the work is synchronous. That is deliberate: actors can be hosted in the page's thread or in a worker, and moving between the two must be a change to one option rather than a rewrite of every call site.

Module exports#

Starting#

The calls#

An actor object carries the interface methods from its idlFactory, plus four things that are always there: id (the ten-byte Uint8Array), callRaw(method, argBytes), queryRaw(method, argBytes) and logs(). Without an idlFactory you get only those — see /docs/web/candid/.

One program, two transports#

This is the shape scripts/web_lib_gate.sh runs twice — once in the page, once in a worker — and asserts gives the same answers:

async function exercise(moxzi, tag) {
  const greeter = await moxzi.install({ name: 'greeter', wasm: './greet.wasm', idlFactory });
  const hello = await greeter.greet('world');
  await greeter.greet('ada');
  const n = await greeter.visitors();
  return { hello, n: String(n) };
}

const page   = await Moxzi.start({ glue });                                 // canPreempt false
const worker = await Moxzi.start({ worker: true, deadlineMs: 2000 });       // canPreempt true

What only a worker can do#

const worker = await Moxzi.start({ worker: true, deadlineMs: 2000 });
const spinner = await worker.install({ name: 'spinner', wasm: './spin.wasm', idlFactory: spinIdl });
try { await spinner.spin(); }
catch (e) { e instanceof ActorError; }   // "spin exceeded its 2000ms deadline and was stopped"

The deadline is a Promise.race against the call; when it wins, recover() runs, the worker is terminated and rebuilt, and every actor is reinstalled and restored from its last committed snapshot — including actors that had nothing to do with the runaway. Recovery is single-flight: several calls in flight when one overruns all land in the same rebuild rather than each starting their own.

withDeadline scopes a different budget to the calls a callback makes — the knights demo uses it because an LLM outcall legitimately takes tens of seconds inside a runtime whose game ticks should die in three:

const r = await moxzi.withDeadline(180_000, () =>
  world.improveKnight(BigInt(kid), api.base, api.key, api.model, prefix));

It is scoped, not concurrent: calls made elsewhere while fn is in flight see the temporary deadline too, so keep the callback's work sequential.

Persistence and spawned actors#

persist() covers what the page installed. Actors created by actors go through the management canister, so their code never crossed into the page and only the runtime knows they exist — that is what saveAll/loadAll are for. From the knights demo and the library gate:

const blob = await moxzi.saveAll();        // every canister, spawned ones included
// … a reload, or a fresh runtime …
const n = await reborn.loadAll(blob);      // how many came back
const back = reborn.actor('nursery', nurseryIdl);

install is also the reload path: with a store, an actor whose state is already saved is restored instead of initialised. Installing a different module over stored state is refused by module hash, naming upgrade() as the call to make instead.

Devtools#

import { attachDevtools } from 'moxzi-web/devtools';
window.__devtools = attachDevtools(moxzi);   // 🔎 badge, bottom right

The panel lists every canister in the runtime, spawned ones included, renders each interface from candidOf(id) as callable forms, and takes logs on click. detach() removes it.

Next#

• /docs/web/candid/ — argument encoding, and why an untyped reply shows numbers instead of field names.
• /docs/web/install/ — package exports, the worker/bundler rule, COOP/COEP.
• /docs/web/limits/ — where this stops matching the IC.