janela 0.1.0 → 0.1.2

package/README.md

@@ -19,8 +19,33 @@ janela build              # .janela/out/my-app  (+ my-app.app on macOS)
 ```
 
 Requirements: Node 18+, a C++ compiler (Xcode CLT on macOS; g++ +
-`libwebkit2gtk-4.1-dev` on Linux). A worked example lives in
-[`examples/demo`](examples/demo) — commands, events, and a file reader.
+`libwebkit2gtk-4.1-dev` on Linux; see [Windows](#windows) below). A worked
+example lives in [`examples/demo`](examples/demo) — commands, events, and a
+file reader.
+
+## Windows
+
+`janela build` produces `.janela/out/<name>.exe` using the WebView2 backend.
+
+**You need a MinGW-targeting clang on `PATH`** — [llvm-mingw][llvm-mingw],
+MSYS2's `clang64` toolchain, or WinLibs. MSVC does **not** work: scriptc's
+runtime uses POSIX types and calls (`ssize_t`, `nanosleep`, `clock_gettime`)
+that the MSVC CRT does not provide. janela checks `clang -dumpmachine` and
+tells you if the wrong one is first on `PATH`.
+
+webview.h's Win32 backend includes `WebView2.h`, which Microsoft ships in a
+nuget package rather than in the Windows SDK, so the first build downloads
+`Microsoft.Web.WebView2` into `.janela/cache/` automatically. To build offline
+or pin your own copy, point `JANELA_WEBVIEW2_INCLUDE` at a directory
+containing `WebView2.h`. No `WebView2Loader.dll` is needed — webview.h has its
+own loader — and end users need only the **WebView2 runtime**, which is
+preinstalled on current Windows 10/11 (it ships with Edge).
+
+Two caveats today: the binary is a console-subsystem app, so a console window
+appears behind the UI (handy for `janela dev`, wrong for shipping), and there
+is no installer step — you get a bare `.exe`, not an MSI.
+
+[llvm-mingw]: https://github.com/mstorsjo/llvm-mingw/releases
 
 ## A project
 
@@ -53,6 +78,48 @@ export function setup(app: JanelaApp): void {
 }
 ```
 
+## Async commands
+
+A command that has to wait — or to chew through real work — should not freeze
+the window. Register it with `commandAsync` and answer whenever you are ready;
+the page keeps using the same `await janela.invoke(...)`.
+
+```ts
+app.commandAsync("wait", (argsJson, resolve, reject) => {
+  const a = JSON.parse(argsJson) as { ms: number };
+  app.sleep(a.ms, () => resolve(JSON.stringify("done")));   // resolve later
+});
+
+// Work that cannot just wait: slice it, yielding to the UI between slices.
+app.commandAsync("countTo", (argsJson, resolve) => {
+  const a = JSON.parse(argsJson) as { n: number };
+  let i = 0;
+  const step = (): void => {
+    const end = Math.min(i + 2_000_000, a.n);
+    for (; i < end; i++) { /* ... */ }
+    if (i < a.n) app.defer(step); else resolve(JSON.stringify(i));
+  };
+  app.defer(step);
+});
+```
+
+- `app.defer(fn)` — run `fn` on the next turn of the host loop.
+- `app.sleep(ms, fn)` — run `fn` after at least `ms`.
+- `resolve(json)` / `reject(json)` settle the page's promise; `reject` makes
+  `await janela.invoke(...)` throw. Settling twice is ignored.
+
+**Use `app.sleep`, not `setTimeout`.** scriptc's own event loop is parked for
+as long as the program sits inside the `run()` FFI call, so `setTimeout`,
+`queueMicrotask` and `await` in host code never fire while the window is open
+(they all run after it closes). janela supplies its own loop instead: a native
+ticker posts work to the UI thread via `webview_dispatch`, and it only runs
+while something is queued, so an idle app costs nothing.
+
+**Still single-threaded.** scriptc's runtime is not thread-safe (concurrent
+calls from several threads abort the process), so host code always runs on the
+UI thread. Async here means *interleaved*, not parallel: a handler that blocks
+without yielding still freezes the window. Slice long work with `defer`.
+
 The backend is ordinary TypeScript with scriptc's stdlib — including a
 `node:fs` subset — so "read a file" or "call an API" is just code in a
 command handler, no plugin layer needed.
@@ -76,8 +143,9 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
   RHS — it is silently miscompiled. Wrap it in any expression (`+ 0`). Plain
   TypeScript is unaffected; only the runtime does FFI, so app code rarely
   meets this.
-- One window per app for now; the run loop is single-threaded, so a slow
-  command blocks the UI (same as a blocking Tauri command handler).
+- One window per app for now. Host code is single-threaded: a synchronous
+  command blocks the UI while it runs — use `commandAsync` + `defer`/`sleep`
+  (see "Async commands") for anything slow.
 - `console.log` from commands goes to stdout — visible under `janela dev`,
   not when launched from Finder.
 
@@ -86,9 +154,28 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
 Early proof of concept, macOS (arm64) and Linux (WebKitGTK). The design
 notes and scriptc findings behind it are in
 [docs/findings.md](docs/findings.md). Not yet: Windows, async commands
-(the run loop is single-threaded), native dialogs/tray/menus, multi-window,
+that run in parallel (host code is single-threaded; `commandAsync` interleaves
+instead), native dialogs/tray/menus, multi-window,
 icons/installers/notarization.
 
+## Releasing
+
+Bump `version` in `package.json` and merge to `main`. The publish workflow
+then does the rest: it compares the version against the registry, and if it
+is new, scaffolds/builds/runs a smoke app on Linux, publishes to npm with
+trusted publishing (OIDC — no token secret), tags the published commit
+`v<version>`, and opens a GitHub release with generated notes.
+
+A merge that does not change the version is a clean no-op: nothing is
+published and no tag is created. If a publish ever succeeds but the tagging
+step does not, npm and git are briefly out of step — reconcile with:
+
+```bash
+git tag -a v<version> -m "janela <version>" <commit>
+git push origin v<version>
+gh release create v<version> --generate-notes --verify-tag
+```
+
 ## License
 
 MIT. Bundles [webview/webview](https://github.com/webview/webview) headers

package/bin/janela.mjs

@@ -54,16 +54,95 @@ function loadConf(root) {
   return c;
 }
 
+// ---- Windows toolchain ------------------------------------------------------
+
+// scriptc's win32 lane is MinGW-shaped twice over: its runtime uses POSIX
+// types the MSVC CRT lacks (ssize_t), and its event loop calls POSIX time
+// APIs that only a full mingw-w64 provides ("the idle sleep is nanosleep
+// (mingw-w64 ships it, over Sleep)" — scr_async.c). So Windows builds need a
+// clang whose DEFAULT target is mingw: llvm-mingw, MSYS2's clang64, or
+// WinLibs. A stock MSVC-targeting clang cannot compile scriptc's runtime, and
+// zig's bundled mingw omits winpthreads, so it cannot either.
+function winCcOrFail() {
+  const probe = spawnSync("clang", ["-dumpmachine"], { encoding: "utf8" });
+  if (probe.status !== 0) {
+    fail(
+      "Windows builds need a MinGW-targeting clang on PATH. Install llvm-mingw " +
+        "(https://github.com/mstorsjo/llvm-mingw/releases) or MSYS2's clang64 toolchain.",
+    );
+  }
+  const triple = probe.stdout.trim();
+  if (!/mingw|windows-gnu/i.test(triple)) {
+    fail(
+      `clang on PATH targets '${triple}', but scriptc's Windows runtime only builds with ` +
+        "MinGW (it uses ssize_t/nanosleep/clock_gettime, which the MSVC CRT lacks). " +
+        "Put a MinGW-targeting clang first on PATH — llvm-mingw " +
+        "(https://github.com/mstorsjo/llvm-mingw/releases) or MSYS2's clang64.",
+    );
+  }
+  return triple;
+}
+
+// ---- WebView2 SDK (Windows only) -------------------------------------------
+
+// webview.h's Win32 backend includes <WebView2.h>, which ships in Microsoft's
+// nuget package rather than the Windows SDK. Fetch it once into the build
+// cache (a .nupkg is a zip) unless the caller points at their own copy.
+const WEBVIEW2_VERSION = "1.0.2903.40";
+
+function webview2Include(cacheDir) {
+  const override = process.env.JANELA_WEBVIEW2_INCLUDE;
+  if (override) {
+    if (!existsSync(join(override, "WebView2.h"))) {
+      fail(`JANELA_WEBVIEW2_INCLUDE=${override} does not contain WebView2.h`);
+    }
+    return override;
+  }
+
+  const sdkDir = join(cacheDir, `webview2-${WEBVIEW2_VERSION}`);
+  const incDir = join(sdkDir, "build", "native", "include");
+  if (existsSync(join(incDir, "WebView2.h"))) return incDir;
+
+  console.log(`janela: fetching WebView2 SDK ${WEBVIEW2_VERSION}`);
+  const zip = join(cacheDir, `webview2-${WEBVIEW2_VERSION}.zip`);
+  const url = `https://www.nuget.org/api/v2/package/Microsoft.Web.WebView2/${WEBVIEW2_VERSION}`;
+  run([
+    "powershell", "-NoProfile", "-NonInteractive", "-Command",
+    `$ErrorActionPreference='Stop';` +
+      `[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12;` +
+      `Invoke-WebRequest -Uri '${url}' -OutFile '${zip}';` +
+      `Expand-Archive -Path '${zip}' -DestinationPath '${sdkDir}' -Force`,
+  ]);
+  if (!existsSync(join(incDir, "WebView2.h"))) {
+    fail(`WebView2 SDK unpacked to ${sdkDir} but no build/native/include/WebView2.h`);
+  }
+  return incDir;
+}
+
 // ---- shim ----------------------------------------------------------------
 
 function buildShim(cacheDir) {
   const src = join(KIT, "shim", "wvshim.cc");
-  const obj = join(cacheDir, "wvshim.o");
-  const lib = join(cacheDir, "libwvshim.a");
+  const win = process.platform === "win32";
+  // On Windows the object file is handed to the link directly: `ar` is not
+  // part of an MSVC toolchain, and a lone object needs no archive index.
+  const obj = join(cacheDir, win ? "wvshim.obj" : "wvshim.o");
+  const lib = win ? obj : join(cacheDir, "libwvshim.a");
   if (existsSync(lib) && statSync(lib).mtimeMs > statSync(src).mtimeMs) return lib;
 
   console.log("janela: compiling webview shim");
   const inc = `-I${join(KIT, "vendor-webview", "core", "include")}`;
+  if (win) {
+    console.log(`janela: building for ${winCcOrFail()}`);
+    run([
+      "clang++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc,
+      // WebView2.h from the nuget SDK, plus mingw's missing EventToken.h.
+      `-I${webview2Include(cacheDir)}`,
+      `-I${join(KIT, "vendor-webview", "compatibility", "mingw", "include")}`,
+      "-DWIN32_LEAN_AND_MEAN", "-D_WIN32_WINNT=0x0601",
+    ]);
+    return lib;
+  }
   if (process.platform === "darwin") {
     run(["clang++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc]);
   } else {
@@ -101,8 +180,36 @@ function ffiManifest(shimLib) {
       returns: "i32",
     },
     { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
+    // async: deferred returns + the UI-thread pump behind app.defer/sleep
+    { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
+    { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
+    { name: "wvTickStart", symbol: "wv_tick_start", params: ["i32", "i32"], returns: "i32" },
+    { name: "wvTickStop", symbol: "wv_tick_stop", params: ["i32"], returns: "i32" },
   ];
 
+  if (process.platform === "win32") {
+    // MinGW ignores MSVC's #pragma comment(lib, ...), so the Win32 imports the
+    // WebView2 backend needs are named explicitly. scriptc's own win32 lane
+    // already adds advapi32/iphlpapi/ws2_32, so those are omitted here.
+    // `c++` pulls libc++ for the shim's std::string/exceptions.
+    //
+    // `pthread` (mingw's libwinpthread) is here to work around an upstream
+    // scriptc bug: its runtime calls clock_gettime/nanosleep, which mingw
+    // declares in <time.h> but implements in winpthreads, and scriptc's win32
+    // link never adds it. Without this the link dies with
+    // "undefined symbol: clock_gettime" — reproducible with a plain
+    // `scriptc build hello.ts` on Windows, no FFI involved.
+    return {
+      ffi_format: 2,
+      functions,
+      libraries: [shimLib],
+      system_libraries: [
+        "c++", "pthread",
+        "ole32", "oleaut32", "shlwapi", "shell32", "user32", "version", "gdi32",
+      ],
+    };
+  }
+
   if (process.platform === "darwin") {
     // scriptc has no -framework support, but `libraries` entries are passed to
     // the link as plain input files and ld64 accepts .tbd stubs.
@@ -180,9 +287,17 @@ function build(root) {
   writeFileSync(join(buildDir, "janela.ffi.json"), JSON.stringify(ffiManifest(shimLib), null, 2) + "\n");
 
   console.log("janela: compiling TypeScript to a native binary");
-  const bin = join(outDir, conf.name);
+  // An explicit --out is used verbatim, so the PE suffix is ours to add.
+  const bin = join(outDir, process.platform === "win32" ? `${conf.name}.exe` : conf.name);
+  // No SCRIPTC_CC/SCRIPTC_TARGET on Windows: scriptc's default driver is
+  // plain `clang`, which is exactly the MinGW-targeting clang checked above.
   run(["node", scriptcBin(), "build", "entry.ts", "--ffi", "janela.ffi.json", "-o", bin], { cwd: buildDir });
 
+  // Symbol/debug metadata is ~16% of the binary and apps don't need it.
+  // (On arm64 macOS, strip re-signs ad-hoc automatically. MinGW keeps DWARF
+  // inside the .exe rather than a side-by-side .pdb, so Windows benefits too.)
+  run(["strip", bin]);
+
   if (process.platform === "darwin") {
     const bundle = join(outDir, `${conf.name}.app`);
     mkdirSync(join(bundle, "Contents", "MacOS"), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "type": "git",
     "url": "git+https://github.com/mmamedel/janela.git"
   },
-  "homepage": "https://github.com/mmamedel/janela#readme",
+  "homepage": "https://mmamedel.github.io/janela/",
   "bugs": {
     "url": "https://github.com/mmamedel/janela/issues"
   },

package/runtime/janela.ts

@@ -22,6 +22,13 @@ declare function wvReplyReset(h: number): number;
 declare function wvReplyPush(h: number, b: number): number;
 declare function wvRun(h: number, cb: (bindIndex: number, seq: number) => number): number;
 declare function wvTerminate(h: number): number;
+declare function wvDefer(h: number): number;
+declare function wvResolve(h: number, id: number, status: number): number;
+declare function wvTickStart(h: number, intervalMs: number): number;
+declare function wvTickStop(h: number): number;
+
+// Bind index the shim uses for a timer tick rather than a page invoke.
+const TICK_BIND = 4294967295;
 
 // Injected into every page before it loads (webview_init).
 const BOOTSTRAP =
@@ -45,6 +52,18 @@ const BOOTSTRAP =
 // scriptc across the FFI boundary — return an error envelope instead.
 export type CommandHandler = (argsJson: string) => string;
 
+/**
+ * An async command: return immediately, answer later. `resolve`/`reject` take
+ * JSON text and settle the page's `await janela.invoke(...)` promise whenever
+ * they are called — from a later defer()/sleep() turn, or from another
+ * command. The window stays responsive for as long as the call is pending.
+ */
+export type AsyncCommandHandler = (
+  argsJson: string,
+  resolve: (json: string) => void,
+  reject: (json: string) => void,
+) => void;
+
 export interface WindowConfig {
   title: string;
   width: number;
@@ -57,6 +76,13 @@ export interface JanelaApp {
   handlers: CommandHandler[];
   /** Register a named command, callable from the page as janela.invoke(name, args). */
   command: (name: string, h: CommandHandler) => void;
+  /** Register a command that answers later; see AsyncCommandHandler. */
+  commandAsync: (name: string, h: AsyncCommandHandler) => void;
+  /** Run fn on the next turn of the host loop — the way to slice long work. */
+  defer: (fn: () => void) => void;
+  /** Run fn after at least ms. The host loop's timer; scriptc's setTimeout
+   *  cannot fire while the window is open (its loop is parked inside run()). */
+  sleep: (ms: number, fn: () => void) => void;
   /** Fire an event into the page; payloadJson must be valid JSON text. */
   emit: (event: string, payloadJson: string) => void;
   /** Close the window and make run() return. */
@@ -144,6 +170,60 @@ export function createApp(cfg: WindowConfig): JanelaApp {
   wvSetSize(h, cfg.width, cfg.height, 0);
   wvInit(h, BOOTSTRAP);
 
+  // ---- the host loop -------------------------------------------------------
+  // scriptc's event loop is parked for as long as the program sits inside the
+  // wvRun() FFI call, so setTimeout/await never fire while the window is open.
+  // These queues are drained instead by TICK_BIND callbacks that the shim's
+  // ticker posts to the UI thread, and the ticker only runs while there is
+  // work — an idle app costs nothing.
+  const asyncNames: string[] = [];
+  const asyncHandlers: AsyncCommandHandler[] = [];
+  let taskFns: (() => void)[] = [];
+  let timerFns: (() => void)[] = [];
+  let timerDue: number[] = [];
+  let ticking = false;
+
+  const wake = (): void => {
+    if (ticking) return;
+    ticking = true;
+    wvTickStart(h, 8);
+  };
+
+  const idle = (): void => {
+    if (!ticking) return;
+    if (taskFns.length > 0 || timerFns.length > 0) return;
+    ticking = false;
+    wvTickStop(h);
+  };
+
+  // One turn of the loop: every task queued so far, plus every due timer.
+  // Tasks queued *by* this turn wait for the next one, so a defer() chain
+  // yields to the UI between slices instead of starving it.
+  const turn = (): void => {
+    const tasks = taskFns;
+    taskFns = [];
+    for (let i = 0; i < tasks.length; i++) tasks[i]();
+
+    if (timerFns.length > 0) {
+      const now = Date.now() + 0;
+      const keptFns: (() => void)[] = [];
+      const keptDue: number[] = [];
+      const fire: (() => void)[] = [];
+      for (let i = 0; i < timerFns.length; i++) {
+        if (timerDue[i] <= now) {
+          fire.push(timerFns[i]);
+        } else {
+          keptFns.push(timerFns[i]);
+          keptDue.push(timerDue[i]);
+        }
+      }
+      timerFns = keptFns;
+      timerDue = keptDue;
+      for (let i = 0; i < fire.length; i++) fire[i]();
+    }
+    idle();
+  };
+
   const app: JanelaApp = {
     handle: h,
     names: [],
@@ -154,6 +234,22 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       app.handlers.push(handler);
     },
 
+    commandAsync: (name, handler) => {
+      asyncNames.push(name);
+      asyncHandlers.push(handler);
+    },
+
+    defer: (fn) => {
+      taskFns.push(fn);
+      wake();
+    },
+
+    sleep: (ms, fn) => {
+      timerFns.push(fn);
+      timerDue.push(Date.now() + (ms > 0 ? ms : 0));
+      wake();
+    },
+
     emit: (event, payloadJson) => {
       wvEval(
         h,
@@ -170,6 +266,12 @@ export function createApp(cfg: WindowConfig): JanelaApp {
       wvSetHtml(h, html);
 
       const rc = wvRun(h, (bindIndex, _seq) => {
+        // A tick is not an invoke: nothing is waiting on a reply, so the
+        // shim never calls webview_return for it.
+        if (bindIndex === TICK_BIND) {
+          turn();
+          return 0;
+        }
         if (bindIndex !== INVOKE) {
           writeReply(h, '"unknown binding"');
           return 1;
@@ -183,6 +285,29 @@ export function createApp(cfg: WindowConfig): JanelaApp {
             return 0;
           }
         }
+        for (let i = 0; i < asyncNames.length; i++) {
+          if (asyncNames[i] === cmd) {
+            // Park the page's promise: the shim holds this call's id and
+            // answers it when resolve/reject reaches wvResolve, whenever
+            // that is. Meanwhile the loop is free to serve other calls.
+            const id = wvDefer(h) + 0;
+            if (id < 0) {
+              writeReply(h, JSON.stringify("cannot defer command: " + cmd));
+              return 1;
+            }
+            const settle = (status: number): ((json: string) => void) => {
+              let done = false;
+              return (json: string) => {
+                if (done) return; // a promise settles once
+                done = true;
+                writeReply(h, json);
+                wvResolve(h, id, status);
+              };
+            };
+            asyncHandlers[i](argsJson, settle(0), settle(1));
+            return 0;
+          }
+        }
         writeReply(h, JSON.stringify("unknown command: " + cmd));
         return 1; // rejects the frontend promise
       }) + 0;

package/shim/wvshim.cc

@@ -13,9 +13,12 @@
 
 #include "webview.h"
 
+#include <atomic>
+#include <chrono>
 #include <cstdint>
 #include <cstring>
 #include <string>
+#include <thread>
 #include <vector>
 
 namespace {
@@ -24,6 +27,13 @@ struct Bind {
   std::string name;
 };
 
+// An invoke whose webview_return was postponed by wv_defer(): the page's
+// promise stays unsettled until TS calls wv_resolve() on a later turn.
+struct Pending {
+  bool used = false;
+  std::string call_id;
+};
+
 struct App {
   webview_t w = nullptr;
   bool used = false;
@@ -38,8 +48,19 @@ struct App {
   std::string cur_id;   // webview's call id, needed by webview_return
   std::string reply;    // response body assembled by TS
   uint32_t seq = 0;
+
+  // ---- async support ----
+  std::vector<Pending> pending;  // deferred invokes, addressed by index
+  bool deferred = false;         // set by wv_defer() during the current call
+  std::thread ticker;            // pure-C++ thread; never touches TS itself
+  std::atomic<bool> ticking{false};
+  std::atomic<int32_t> tick_ms{16};
 };
 
+// Bind index handed to the TS callback for a timer tick rather than an
+// invoke. Real bind indices are small sequential integers.
+const uint32_t TICK_BIND = 0xffffffffu;
+
 // Fixed-size table: handles are indices, never pointers.
 App g_apps[8];
 
@@ -65,14 +86,37 @@ void trampoline(const char *id, const char *req, void *arg) {
   a->req = req ? req : "";
   a->cur_id = id ? id : "";
   a->reply.clear();
+  a->deferred = false;
   a->seq++;
 
   // Re-entrancy: this call lands back in TS, which will call wv_req_byte()
   // etc. back into this shim before returning.
   int32_t status = a->cb(bind_index, a->seq, a->cb_ctx);
 
+  // An async handler called wv_defer(): the call id now lives in the pending
+  // table and wv_resolve() will answer the page later. Returning now would
+  // settle the promise with a stale value.
+  if (a->deferred) {
+    a->deferred = false;
+    a->cur_id.clear();
+    return;
+  }
+
   webview_return(a->w, a->cur_id.c_str(), status,
                  a->reply.empty() ? "null" : a->reply.c_str());
+  // wv_defer() treats a non-empty cur_id as "an invoke is in flight". Clearing
+  // it here means a defer from anywhere else — a tick, say — fails with -1
+  // instead of stealing this already-answered call's id.
+  a->cur_id.clear();
+}
+
+// Runs on the UI thread (posted by the ticker via webview_dispatch), so the
+// TS it calls stays single-threaded — scriptc's runtime is NOT thread-safe.
+void tick_on_ui_thread(webview_t, void *arg) {
+  App *a = &g_apps[reinterpret_cast<uintptr_t>(arg)];
+  if (!a->used || !a->cb) return;  // app quit between dispatch and delivery
+  a->seq++;
+  a->cb(TICK_BIND, a->seq, a->cb_ctx);
 }
 
 }  // namespace
@@ -84,7 +128,19 @@ int32_t wv_create(int32_t debug) {
     if (g_apps[i].used) continue;
     webview_t w = webview_create(debug, nullptr);
     if (!w) return -1;
-    g_apps[i] = App{};
+    // Field-wise reset: App holds a thread and atomics, so it is not
+    // copy-assignable from a temporary.
+    g_apps[i].binds.clear();
+    g_apps[i].cb = nullptr;
+    g_apps[i].cb_ctx = nullptr;
+    g_apps[i].req.clear();
+    g_apps[i].cur_id.clear();
+    g_apps[i].reply.clear();
+    g_apps[i].seq = 0;
+    g_apps[i].pending.clear();
+    g_apps[i].deferred = false;
+    g_apps[i].ticking.store(false);
+    g_apps[i].tick_ms.store(16);
     g_apps[i].w = w;
     g_apps[i].used = true;
     return i;
@@ -170,6 +226,75 @@ int32_t wv_reply_push(int32_t h, int32_t byte) {
   return 0;
 }
 
+// ---- async: deferred returns + a UI-thread pump -----------------------------
+//
+// scriptc's own event loop does not run while the program sits inside an FFI
+// call, and wv_run() is one such call for the app's whole life — so setTimeout
+// and promise continuations in TS never fire while the window is open. These
+// four functions supply the missing loop: TS may postpone an invoke's answer
+// (wv_defer), answer it later (wv_resolve), and get called back periodically
+// on the UI thread to make progress (wv_tick_start / wv_tick_stop).
+
+// Postpone the answer to the invoke being handled right now. Returns a
+// pending id to hand back to wv_resolve(), or -1 outside a bind callback.
+int32_t wv_defer(int32_t h) {
+  App *a = app_at(h);
+  if (!a || a->cur_id.empty()) return -1;
+  for (size_t i = 0; i < a->pending.size(); i++) {
+    if (!a->pending[i].used) {
+      a->pending[i].used = true;
+      a->pending[i].call_id = a->cur_id;
+      a->deferred = true;
+      return static_cast<int32_t>(i);
+    }
+  }
+  a->pending.push_back(Pending{true, a->cur_id});
+  a->deferred = true;
+  return static_cast<int32_t>(a->pending.size() - 1);
+}
+
+// Answer a deferred invoke with whatever TS has staged via wv_reply_push().
+// status 0 resolves the page's promise, non-zero rejects it.
+int32_t wv_resolve(int32_t h, int32_t id, int32_t status) {
+  App *a = app_at(h);
+  if (!a || id < 0 || static_cast<size_t>(id) >= a->pending.size()) return -1;
+  Pending &p = a->pending[id];
+  if (!p.used) return -1;
+  webview_return(a->w, p.call_id.c_str(), status,
+                 a->reply.empty() ? "null" : a->reply.c_str());
+  p.used = false;
+  p.call_id.clear();
+  a->reply.clear();
+  return 0;
+}
+
+// Start pumping TS with TICK_BIND callbacks every interval_ms. The thread
+// itself only sleeps and posts; all TS execution happens on the UI thread.
+int32_t wv_tick_start(int32_t h, int32_t interval_ms) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  a->tick_ms = interval_ms > 0 ? interval_ms : 16;
+  if (a->ticking.exchange(true)) return 0;  // already running
+  uintptr_t idx = static_cast<uintptr_t>(h);
+  a->ticker = std::thread([a, idx]() {
+    while (a->ticking.load()) {
+      std::this_thread::sleep_for(
+          std::chrono::milliseconds(a->tick_ms.load()));
+      if (!a->ticking.load()) break;
+      webview_dispatch(a->w, tick_on_ui_thread, reinterpret_cast<void *>(idx));
+    }
+  });
+  return 0;
+}
+
+int32_t wv_tick_stop(int32_t h) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  if (!a->ticking.exchange(false)) return 0;
+  if (a->ticker.joinable()) a->ticker.join();
+  return 0;
+}
+
 // Blocks for the app's lifetime; dispatches bind calls into `cb`.
 int32_t wv_run(int32_t h, int32_t (*cb)(uint32_t, uint32_t, void *),
                void *cb_ctx) {
@@ -178,6 +303,9 @@ int32_t wv_run(int32_t h, int32_t (*cb)(uint32_t, uint32_t, void *),
   a->cb = cb;
   a->cb_ctx = cb_ctx;
   int rc = webview_run(a->w);
+  // The ticker must not outlive the callback it drives.
+  a->ticking.store(false);
+  if (a->ticker.joinable()) a->ticker.join();
   a->cb = nullptr;  // callback must not outlive the call, per lifetime:"call"
   a->cb_ctx = nullptr;
   return rc;
@@ -192,6 +320,8 @@ int32_t wv_terminate(int32_t h) {
 int32_t wv_destroy(int32_t h) {
   App *a = app_at(h);
   if (!a) return -1;
+  a->ticking.store(false);
+  if (a->ticker.joinable()) a->ticker.join();
   webview_destroy(a->w);
   a->used = false;
   a->w = nullptr;

package/templates/index.html

@@ -14,6 +14,7 @@
       <input id="a" type="number" value="2" /> +
       <input id="b" type="number" value="40" />
       <button id="add">add</button>
+      <button id="wait">wait 2s (async)</button>
       <button id="quit">Quit</button>
     </p>
     <pre id="out">booting…</pre>
@@ -41,6 +42,15 @@
           const sum = await janela.invoke("add", { a, b });
           out.textContent = `add(${a}, ${b}) -> ${sum}`;
         };
+        // The window stays responsive while this is pending: the spinner keeps
+        // animating and "add" still works.
+        document.getElementById("wait").onclick = async (e) => {
+          e.target.disabled = true;
+          out.textContent = "waiting… (try 'add' — it still answers)";
+          out.textContent = await janela.invoke("wait", { ms: 2000 });
+          e.target.disabled = false;
+        };
+
         document.getElementById("quit").onclick = () => janela.invoke("quit");
       };
     </script>

package/templates/main.ts

@@ -30,6 +30,15 @@ export function setup(app: JanelaApp): void {
     return "null";
   });
 
+  // An async command: answers later, without freezing the window. The page
+  // still just does `await janela.invoke("wait", { ms: 1000 })`.
+  app.commandAsync("wait", (argsJson, resolve) => {
+    const a = JSON.parse(argsJson) as { ms: number };
+    app.sleep(a.ms, () => {
+      resolve(JSON.stringify("waited " + a.ms + "ms without blocking the UI"));
+    });
+  });
+
   app.command("quit", (_argsJson) => {
     app.quit();
     return "null";