Embedders cannot offer async handlers: microtasks never drain while the host owns the thread (and library mode refuses async)

[mmamedel]

Embedders currently cannot let user code write async handlers, because promise continuations never run while the host owns the main thread. This is a narrower request than #260 (which I closed as unusable for us) — it asks for microtask draining only, and explicitly does not ask scriptc to own a clock, threads, or an event loop.

Version: scriptc 0.0.35, macOS 26.5 arm64.

The two halves

Executable lane — the queue exists but is never serviced during the app's life. A host that owns the loop re-enters the program through a retained callback; a continuation scheduled during one entry has still not run at the next entry:

let flag = "not-run";
// invoked from the host, entry #1
Promise.resolve().then(() => { flag = "MICROTASK RAN"; });
return "scheduled, flag=" + flag;
// invoked from the host, entry #2 — a separate call
return "flag=" + flag;

1st: scheduled, flag=not-run
2nd (separate re-entry): flag=not-run

The continuation only runs once the program's main body returns, which for an embedded app means "at exit".

Library mode — async is refused outright, even with no timers anywhere in the graph:

async function slowAdd(a: number): Promise<number> { return a + 1; }

SC4005: library mode requires an async_free module graph, and this graph reaches an async function ('slowAdd')

What would unblock it

A host-callable microtask drain — "run pending promise continuations, then return":

• in the executable lane, callable from a host that owns the main thread;
• in library mode, an exported <prefix>_drain (alongside <prefix>_reset), together with permitting async functions in the graph.

Microtasks are not timers. Library mode's stated contract — "v1 library artifacts link no event loop, install no signal handlers, and create no threads" — is preserved exactly: draining a queue needs no clock, no threads and no signal handlers. The host keeps ownership of time; it just gets a way to say "now run what's ready".

Why this is worth it (and why it differs from #260)

I closed #260 because it asked for a general loop pump, and we could not consume it: our framework has to work in library mode too, where there is no loop to pump. This ask is consumable in both lanes precisely because it doesn't involve the loop.

Concretely, it is the difference between an embedder's users writing this:

app.commandAsync("load", (args, resolve) => {
  app.readFileAsync(args.path, (err, text) => resolve(transform(text)));
});

and this:

app.command("load", async (args) => {
  const text = await app.readFile(args.path);
  return transform(text);
});

The second is what a TypeScript developer expects to write. The host can already resolve the promise — in our design the shell owns the timers and file I/O and calls back into the compiled code — so the only missing piece is a point at which continuations are allowed to run.

Context

janela — a Tauri-style desktop framework, TypeScript backend compiled by scriptc, OS webview for the window, no JS engine bundled. It now runs on macOS, Linux, Windows, and on iOS via library mode. Async works today through explicit callbacks (commandAsync(name, (args, resolve) => …)), with the host owning a due-ordered timer queue and re-entering the compiled code when work is due — so we are not blocked. But we cannot offer idiomatic async/await to our users on either lane, and the failure mode on the executable lane is unkind: an async handler compiles, looks correct, and silently never resolves.

Happy to test a prototype against both lanes if that would help.