janela 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateus Lage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# janela
+
+> *janela* — Portuguese for **window**.
+
+Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no
+Electron. The backend is TypeScript compiled to a native binary by
+[scriptc](https://scriptc.dev); the window is the OS webview via
+[webview/webview](https://github.com/webview/webview) (WKWebView on macOS,
+WebKitGTK on Linux). Binaries come out ~500 KB.
+
+## Quick start
+
+```bash
+npm install -g janela     # or: npx janela init my-app
+janela init my-app        # (or `jn init my-app`)
+cd my-app
+janela dev                # build + run with logs in the terminal
+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.
+
+## A project
+
+```
+my-app/
+├── index.html          frontend — any HTML/JS; calls janela.invoke() / janela.listen()
+├── src-host/main.ts    backend — exports setup(app), registers commands
+└── janela.conf.json    name, bundle identifier, version, window
+```
+
+Frontend API (injected before page load):
+
+```js
+const sum = await janela.invoke("add", { a: 2, b: 40 }); // call a backend command
+janela.listen("added", (payload) => { ... });            // backend-fired events
+```
+
+Backend API (`src-host/main.ts`):
+
+```ts
+import type { JanelaApp } from "./janela";
+
+export function setup(app: JanelaApp): void {
+  app.command("add", (argsJson) => {          // args in / result out as JSON text
+    const a = JSON.parse(argsJson) as { a: number; b: number };
+    app.emit("added", JSON.stringify(a.a + a.b));  // push an event to the page
+    return JSON.stringify(a.a + a.b);
+  });
+  // app.quit() closes the window and returns from run()
+}
+```
+
+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.
+
+## What the CLI hides
+
+`janela build` assembles `.janela/build/` (runtime + your `main.ts` +
+generated `frontend.ts`/`config.ts`/`entry.ts` + a platform FFI manifest),
+compiles the C shim over webview.h once into `.janela/cache/`, then runs
+scriptc. On macOS the frameworks are linked as SDK `.tbd` stubs (scriptc has
+no `-framework` support) and the binary is wrapped into an ad-hoc-signed
+`.app` bundle.
+
+## Constraints inherited from scriptc 0.0.32
+
+- Command args/results cross the boundary as **JSON text** — handlers
+  `JSON.parse` in and `JSON.stringify` out. The runtime keeps the byte channel
+  ASCII by `\uXXXX`-escaping non-ASCII (scriptc strings can't hold lone
+  surrogates, and `JSON.parse` is the reliable reassembly point).
+- Never use a bare FFI call as a complete variable initializer or assignment
+  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).
+- `console.log` from commands goes to stdout — visible under `janela dev`,
+  not when launched from Finder.
+
+## Status
+
+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,
+icons/installers/notarization.
+
+## License
+
+MIT. Bundles [webview/webview](https://github.com/webview/webview) headers
+(MIT, © Serge Zaitsev and contributors).

package/bin/janela.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// janela — the CLI (the tauri-cli analogue).
+//
+//   janela init <name>   scaffold a new project
+//   janela build         compile the project to a native binary (+ .app on macOS)
+//   janela dev           build, then run the binary with logs in the terminal
+//
+// A project is: index.html (frontend), src-host/main.ts (commands),
+// janela.conf.json (window + bundle config). Everything else — the C shim over
+// webview.h, the vendored webview, the scriptc runtime library, the FFI
+// manifest — lives in this package and is assembled into .janela/ at build time.
+
+import { spawnSync } from "node:child_process";
+import {
+  cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(join(KIT, "package.json"));
+
+function fail(msg) {
+  console.error(`janela: ${msg}`);
+  process.exit(1);
+}
+
+function run(argv, opts = {}) {
+  const r = spawnSync(argv[0], argv.slice(1), { stdio: "inherit", ...opts });
+  if (r.status !== 0) fail(`command failed (${r.status ?? r.error}): ${argv.join(" ")}`);
+}
+
+function capture(argv) {
+  const r = spawnSync(argv[0], argv.slice(1), { encoding: "utf8" });
+  if (r.status !== 0) fail(`command failed: ${argv.join(" ")}`);
+  return r.stdout.trim();
+}
+
+function scriptcBin() {
+  const pkg = require.resolve("scriptc/package.json");
+  const meta = JSON.parse(readFileSync(pkg, "utf8"));
+  const rel = typeof meta.bin === "string" ? meta.bin : meta.bin.scriptc;
+  return join(dirname(pkg), rel);
+}
+
+function loadConf(root) {
+  const p = join(root, "janela.conf.json");
+  if (!existsSync(p)) fail("no janela.conf.json here — run from a project root (or `janela init <name>`)");
+  const c = JSON.parse(readFileSync(p, "utf8"));
+  for (const k of ["name", "identifier", "window"]) {
+    if (!c[k]) fail(`janela.conf.json is missing '${k}'`);
+  }
+  return c;
+}
+
+// ---- shim ----------------------------------------------------------------
+
+function buildShim(cacheDir) {
+  const src = join(KIT, "shim", "wvshim.cc");
+  const obj = join(cacheDir, "wvshim.o");
+  const lib = 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 (process.platform === "darwin") {
+    run(["clang++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc]);
+  } else {
+    const cflags = capture(["pkg-config", "--cflags", "gtk+-3.0", "webkit2gtk-4.1"]).split(/\s+/).filter(Boolean);
+    run(["g++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc, ...cflags]);
+  }
+  run(["ar", "rcs", lib, obj]);
+  return lib;
+}
+
+// ---- FFI manifest ---------------------------------------------------------
+
+const STR = (name, symbol) => ({ name, symbol, params: ["i32", "string"], returns: "i32" });
+
+function ffiManifest(shimLib) {
+  const functions = [
+    { name: "wvCreate", symbol: "wv_create", params: ["i32"], returns: "i32" },
+    STR("wvSetTitle", "wv_set_title"),
+    { name: "wvSetSize", symbol: "wv_set_size", params: ["i32", "i32", "i32", "i32"], returns: "i32" },
+    STR("wvSetHtml", "wv_set_html"),
+    STR("wvInit", "wv_init"),
+    STR("wvEval", "wv_eval"),
+    STR("wvBind", "wv_bind"),
+    { name: "wvReqLen", symbol: "wv_req_len", params: ["i32"], returns: "i32" },
+    { name: "wvReqByte", symbol: "wv_req_byte", params: ["i32", "i32"], returns: "i32" },
+    { name: "wvReplyReset", symbol: "wv_reply_reset", params: ["i32"], returns: "i32" },
+    { name: "wvReplyPush", symbol: "wv_reply_push", params: ["i32", "i32"], returns: "i32" },
+    {
+      name: "wvRun", symbol: "wv_run",
+      params: [
+        "i32",
+        { callback: { id: "run", params: ["u32", "u32", { context: "run" }], returns: "i32", lifetime: "call" } },
+        { context: "run" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
+  ];
+
+  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.
+    const sdk = capture(["xcrun", "--sdk", "macosx", "--show-sdk-path"]);
+    return {
+      ffi_format: 2,
+      functions,
+      libraries: [
+        shimLib,
+        join(sdk, "System/Library/Frameworks/WebKit.framework/WebKit.tbd"),
+        join(sdk, "System/Library/Frameworks/Cocoa.framework/Cocoa.tbd"),
+      ],
+      system_libraries: ["c++"],
+    };
+  }
+  return {
+    ffi_format: 2,
+    functions,
+    libraries: [shimLib],
+    system_libraries: [
+      "stdc++", "webkit2gtk-4.1", "javascriptcoregtk-4.1", "gtk-3", "gdk-3",
+      "soup-3.0", "gio-2.0", "gobject-2.0", "glib-2.0", "gmodule-2.0",
+      "pango-1.0", "pangocairo-1.0", "harfbuzz", "atk-1.0", "cairo",
+      "cairo-gobject", "gdk_pixbuf-2.0", "z", "pthread",
+    ],
+  };
+}
+
+// ---- build ----------------------------------------------------------------
+
+function build(root) {
+  const conf = loadConf(root);
+  const buildDir = join(root, ".janela", "build");
+  const cacheDir = join(root, ".janela", "cache");
+  const outDir = join(root, ".janela", "out");
+  for (const d of [buildDir, cacheDir, outDir]) mkdirSync(d, { recursive: true });
+
+  const shimLib = buildShim(cacheDir);
+
+  // Assemble the compile unit: runtime + user's commands + generated modules.
+  cpSync(join(KIT, "runtime", "janela.ts"), join(buildDir, "janela.ts"));
+  const mainSrc = join(root, "src-host", "main.ts");
+  if (!existsSync(mainSrc)) fail("missing src-host/main.ts");
+  cpSync(mainSrc, join(buildDir, "main.ts"));
+
+  const htmlSrc = join(root, "index.html");
+  if (!existsSync(htmlSrc)) fail("missing index.html");
+  const html = readFileSync(htmlSrc, "utf8");
+  writeFileSync(
+    join(buildDir, "frontend.ts"),
+    `// Generated by janela from index.html — do not edit.\nexport const INDEX_HTML: string = ${JSON.stringify(html)};\n`,
+  );
+
+  const w = conf.window;
+  writeFileSync(
+    join(buildDir, "config.ts"),
+    `// Generated by janela from janela.conf.json — do not edit.\n` +
+      `export const WINDOW = { title: ${JSON.stringify(String(w.title ?? conf.name))}, ` +
+      `width: ${Number(w.width ?? 800)}, height: ${Number(w.height ?? 600)} };\n`,
+  );
+
+  writeFileSync(
+    join(buildDir, "entry.ts"),
+    `// Generated by janela — do not edit.\n` +
+      `import { createApp } from "./janela";\n` +
+      `import { WINDOW } from "./config";\n` +
+      `import { INDEX_HTML } from "./frontend";\n` +
+      `import { setup } from "./main";\n\n` +
+      `const app = createApp(WINDOW);\n` +
+      `setup(app);\n` +
+      `const rc = app.run(INDEX_HTML) + 0;\n` +
+      `console.log("[janela] run returned", rc);\n`,
+  );
+
+  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);
+  run(["node", scriptcBin(), "build", "entry.ts", "--ffi", "janela.ffi.json", "-o", bin], { cwd: buildDir });
+
+  if (process.platform === "darwin") {
+    const bundle = join(outDir, `${conf.name}.app`);
+    mkdirSync(join(bundle, "Contents", "MacOS"), { recursive: true });
+    cpSync(bin, join(bundle, "Contents", "MacOS", conf.name));
+    writeFileSync(
+      join(bundle, "Contents", "Info.plist"),
+      `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>${conf.name}</string>
+  <key>CFBundleDisplayName</key><string>${conf.name}</string>
+  <key>CFBundleIdentifier</key><string>${conf.identifier}</string>
+  <key>CFBundleExecutable</key><string>${conf.name}</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleVersion</key><string>${conf.version ?? "0.1.0"}</string>
+  <key>CFBundleShortVersionString</key><string>${conf.version ?? "0.1.0"}</string>
+  <key>NSHighResolutionCapable</key><true/>
+</dict>
+</plist>
+`,
+    );
+    spawnSync("codesign", ["--force", "--sign", "-", bundle]);
+    console.log(`janela: built ${relative(root, bin)} and ${relative(root, bundle)}`);
+  } else {
+    console.log(`janela: built ${relative(root, bin)}`);
+  }
+  return bin;
+}
+
+// ---- init -----------------------------------------------------------------
+
+function init(name) {
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) fail("usage: janela init <name> (lowercase, digits, dashes)");
+  const dir = resolve(process.cwd(), name);
+  if (existsSync(dir)) fail(`${name}/ already exists`);
+  mkdirSync(join(dir, "src-host"), { recursive: true });
+
+  // Installed from the registry (this file lives under node_modules) →
+  // depend on the published version; a source checkout → a file: link.
+  const kitPkg = JSON.parse(readFileSync(join(KIT, "package.json"), "utf8"));
+  const janelaDep = KIT.includes(`${sep}node_modules${sep}`)
+    ? `^${kitPkg.version}`
+    : `file:${relative(dir, KIT) || "."}`;
+
+  const t = (f) => readFileSync(join(KIT, "templates", f), "utf8").replaceAll("__NAME__", name);
+  writeFileSync(join(dir, "index.html"), t("index.html"));
+  writeFileSync(join(dir, "src-host", "main.ts"), t("main.ts"));
+  writeFileSync(join(dir, "janela.conf.json"), t("janela.conf.json"));
+  writeFileSync(join(dir, ".gitignore"), ".janela/\nnode_modules/\n");
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name,
+        private: true,
+        scripts: { dev: "janela dev", build: "janela build" },
+        devDependencies: { janela: janelaDep },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  console.log(`janela: created ${name}/ — next: cd ${name} && janela dev`);
+}
+
+// ---- main -----------------------------------------------------------------
+
+const [cmd, arg] = process.argv.slice(2);
+switch (cmd) {
+  case "init":
+    init(arg);
+    break;
+  case "build":
+    build(process.cwd());
+    break;
+  case "dev": {
+    const bin = build(process.cwd());
+    console.log("janela: running (close the window or Ctrl-C to stop)");
+    run([bin]);
+    break;
+  }
+  default:
+    console.log("usage: janela init <name> | janela build | janela dev");
+    process.exit(cmd ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "janela",
+  "version": "0.1.0",
+  "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
+  "type": "module",
+  "bin": {
+    "janela": "bin/janela.mjs",
+    "jn": "bin/janela.mjs"
+  },
+  "dependencies": {
+    "scriptc": "0.0.32"
+  },
+  "license": "MIT",
+  "author": "Mateus Lage",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmamedel/janela.git"
+  },
+  "homepage": "https://github.com/mmamedel/janela#readme",
+  "bugs": {
+    "url": "https://github.com/mmamedel/janela/issues"
+  },
+  "keywords": [
+    "desktop",
+    "webview",
+    "typescript",
+    "native",
+    "tauri",
+    "electron-alternative",
+    "scriptc"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "runtime/",
+    "shim/",
+    "templates/",
+    "vendor-webview/core/include/",
+    "vendor-webview/LICENSE"
+  ]
+}

package/runtime/janela.ts

@@ -0,0 +1,193 @@
+// janela.ts — the janela runtime, compiled into the app by scriptc.
+//
+// The Tauri-shaped surface: one `__invoke` binding carries every command as a
+// (name, argsJson) envelope, dispatched to handlers registered on the app
+// object. Backend→frontend events ride wv_eval into the injected bootstrap.
+//
+// NOTE ON STYLE: every FFI call whose result initializes a variable is written
+// `f(...) + 0`. scriptc 0.0.32 miscompiles a bare FFI call used as a complete
+// initializer/assignment RHS (see FINDINGS.md); any enclosing expression is
+// the workaround.
+
+declare function wvCreate(debug: number): number;
+declare function wvSetTitle(h: number, title: string): number;
+declare function wvSetSize(h: number, w: number, ht: number, hint: number): number;
+declare function wvSetHtml(h: number, html: string): number;
+declare function wvInit(h: number, js: string): number;
+declare function wvEval(h: number, js: string): number;
+declare function wvBind(h: number, name: string): number;
+declare function wvReqLen(h: number): number;
+declare function wvReqByte(h: number, i: number): number;
+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;
+
+// Injected into every page before it loads (webview_init).
+const BOOTSTRAP =
+  "window.__wvListeners = {};" +
+  "window.janela = {" +
+  "  invoke: function (cmd, args) {" +
+  "    return window.__invoke(cmd, JSON.stringify(args === undefined ? null : args));" +
+  "  }," +
+  "  listen: function (event, cb) {" +
+  "    if (!window.__wvListeners[event]) window.__wvListeners[event] = [];" +
+  "    window.__wvListeners[event].push(cb);" +
+  "  }," +
+  "};" +
+  "window.__wvEmit = function (event, payload) {" +
+  "  var cbs = window.__wvListeners[event] || [];" +
+  "  for (var i = 0; i < cbs.length; i++) cbs[i](payload);" +
+  "};";
+
+// Handlers receive the invoke args as JSON text and must return JSON text
+// (what the frontend promise resolves with). Throwing is not supported by
+// scriptc across the FFI boundary — return an error envelope instead.
+export type CommandHandler = (argsJson: string) => string;
+
+export interface WindowConfig {
+  title: string;
+  width: number;
+  height: number;
+}
+
+export interface JanelaApp {
+  handle: number;
+  names: string[];
+  handlers: CommandHandler[];
+  /** Register a named command, callable from the page as janela.invoke(name, args). */
+  command: (name: string, h: CommandHandler) => 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. */
+  quit: () => void;
+  /** Show the page and block until the window closes. Returns the run status. */
+  run: (html: string) => number;
+}
+
+const HEX = "0123456789abcdef";
+
+function uEscape(unit: number): string {
+  return (
+    "\\u" +
+    HEX.charAt((unit >> 12) & 0xf) +
+    HEX.charAt((unit >> 8) & 0xf) +
+    HEX.charAt((unit >> 4) & 0xf) +
+    HEX.charAt(unit & 0xf)
+  );
+}
+
+// The request arrives as UTF-8 JSON bytes. scriptc strings cannot hold lone
+// surrogates (String.fromCharCode(0xd83d) yields a replacement char), so we
+// never build non-ASCII chars directly: every code point >= 0x80 is re-emitted
+// as a JSON \uXXXX escape (a surrogate PAIR of escapes for astral planes),
+// which JSON.parse reconstructs correctly. Legal only because the payload is
+// always JSON, where non-ASCII can only occur inside strings.
+function readRequest(h: number): string {
+  let out = "";
+  const n = wvReqLen(h) + 0;
+  let i = 0;
+  while (i < n) {
+    const b0 = wvReqByte(h, i) + 0;
+    i = i + 1;
+    let cp = b0;
+    if ((b0 & 0xe0) === 0xc0 && i < n) {
+      cp = ((b0 & 0x1f) << 6) | (wvReqByte(h, i) & 0x3f);
+      i = i + 1;
+    } else if ((b0 & 0xf0) === 0xe0 && i + 1 < n) {
+      cp = ((b0 & 0x0f) << 12) | ((wvReqByte(h, i) & 0x3f) << 6) | (wvReqByte(h, i + 1) & 0x3f);
+      i = i + 2;
+    } else if ((b0 & 0xf8) === 0xf0 && i + 2 < n) {
+      cp =
+        ((b0 & 0x07) << 18) |
+        ((wvReqByte(h, i) & 0x3f) << 12) |
+        ((wvReqByte(h, i + 1) & 0x3f) << 6) |
+        (wvReqByte(h, i + 2) & 0x3f);
+      i = i + 3;
+    }
+    if (cp < 0x80) {
+      out = out + String.fromCharCode(cp);
+    } else if (cp < 0x10000) {
+      out = out + uEscape(cp);
+    } else {
+      const v = cp - 0x10000;
+      out = out + uEscape(0xd800 + (v >> 10)) + uEscape(0xdc00 + (v & 0x3ff));
+    }
+  }
+  return out;
+}
+
+// The reply must be valid JSON when it reaches the page. Non-ASCII chars can
+// only legally occur inside JSON strings, where a \uXXXX escape is always
+// equivalent — so escaping every char >127 keeps the byte channel ASCII-clean
+// (surrogate halves escape individually, which JSON also permits).
+function writeReply(h: number, body: string): void {
+  wvReplyReset(h);
+  for (let i = 0; i < body.length; i++) {
+    const c = body.charCodeAt(i);
+    if (c < 0x80) {
+      wvReplyPush(h, c);
+    } else {
+      wvReplyPush(h, 92); // backslash
+      wvReplyPush(h, 117); // 'u'
+      wvReplyPush(h, HEX.charCodeAt((c >> 12) & 0xf));
+      wvReplyPush(h, HEX.charCodeAt((c >> 8) & 0xf));
+      wvReplyPush(h, HEX.charCodeAt((c >> 4) & 0xf));
+      wvReplyPush(h, HEX.charCodeAt(c & 0xf));
+    }
+  }
+}
+
+export function createApp(cfg: WindowConfig): JanelaApp {
+  const h = wvCreate(0) + 0;
+  wvSetTitle(h, cfg.title);
+  wvSetSize(h, cfg.width, cfg.height, 0);
+  wvInit(h, BOOTSTRAP);
+
+  const app: JanelaApp = {
+    handle: h,
+    names: [],
+    handlers: [],
+
+    command: (name, handler) => {
+      app.names.push(name);
+      app.handlers.push(handler);
+    },
+
+    emit: (event, payloadJson) => {
+      wvEval(
+        h,
+        "window.__wvEmit(" + JSON.stringify(event) + "," + payloadJson + ");",
+      );
+    },
+
+    quit: () => {
+      wvTerminate(h);
+    },
+
+    run: (html) => {
+      const INVOKE = wvBind(h, "__invoke") + 0;
+      wvSetHtml(h, html);
+
+      const rc = wvRun(h, (bindIndex, _seq) => {
+        if (bindIndex !== INVOKE) {
+          writeReply(h, '"unknown binding"');
+          return 1;
+        }
+        const env = JSON.parse(readRequest(h)) as string[];
+        const cmd = env[0];
+        const argsJson = env[1];
+        for (let i = 0; i < app.names.length; i++) {
+          if (app.names[i] === cmd) {
+            writeReply(h, app.handlers[i](argsJson));
+            return 0;
+          }
+        }
+        writeReply(h, JSON.stringify("unknown command: " + cmd));
+        return 1; // rejects the frontend promise
+      }) + 0;
+      return rc;
+    },
+  };
+  return app;
+}