janela 0.13.0 → 0.13.1

package/bin/janela.mjs

@@ -18,6 +18,11 @@ import { createServer } from "node:net";
 import { createRequire } from "node:module";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  ANDROID_ABI, ANDROID_TARGET_SDK, androidConf, ffiManifest, iosConf,
+  libraryProfile, mimeFor, NAME_RE, patchPeSubsystem, PeError,
+  rewriteHostSpecifier, suggestName,
+} from "./lib.mjs";
 
 const KIT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(join(KIT, "package.json"));
@@ -81,30 +86,28 @@ function viteConfigPath(root) {
   return null;
 }
 
-function viteBin(root) {
-  const p = join(root, "node_modules", ".bin", process.platform === "win32" ? "vite.cmd" : "vite");
-  if (!existsSync(p)) {
-    fail(
-      "this project has a vite config but no local vite — run your package manager's " +
-        "install first (npm install / pnpm install)",
-    );
-  }
-  return p;
+// How to run the project's own vite.
+//
+// The `.bin` entry is a .cmd shim on Windows and, since the CVE-2024-27980
+// fix, Node refuses to spawn a .cmd without a shell. `janela dev` passed
+// `shell: true` and worked; `janela build` did not, so building any Vite
+// template on Windows died with `spawnSync ...\vite.cmd EINVAL`. Prefer
+// vite's own JS entry run with this Node: no shim, no shell, and identical on
+// every platform. The shim stays as a fallback for layouts that hide the
+// package but keep the bin.
+function viteCommand(root) {
+  const js = join(root, "node_modules", "vite", "bin", "vite.js");
+  if (existsSync(js)) return { argv: [process.execPath, js], shell: false };
+
+  const shim = join(root, "node_modules", ".bin", process.platform === "win32" ? "vite.cmd" : "vite");
+  if (existsSync(shim)) return { argv: [shim], shell: process.platform === "win32" };
+
+  fail(
+    "this project has a vite config but no local vite — run your package manager's " +
+      "install first (npm install / pnpm install)",
+  );
 }
 
-const MIME = {
-  ".css": "text/css", ".js": "text/javascript", ".json": "application/json",
-  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
-  ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif",
-  ".svg": "image/svg+xml", ".ico": "image/x-icon",
-  ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
-  ".mp3": "audio/mpeg", ".mp4": "video/mp4", ".webm": "video/webm",
-};
-
-function mimeFor(p) {
-  const dot = p.lastIndexOf(".");
-  return (dot < 0 ? null : MIME[p.slice(dot).toLowerCase()]) ?? "application/octet-stream";
-}
 
 // A dist-relative reference ("/assets/x.js", "./assets/x.js") → absolute path,
 // or null when it points outside the build (a CDN URL, a data: URI, an anchor).
@@ -186,7 +189,8 @@ function frontendHtml(root, conf, devUrl) {
 
   if (viteConfigPath(root)) {
     console.log("janela: building the frontend with vite");
-    run([viteBin(root), "build"], { cwd: root });
+    const viteCmd = viteCommand(root);
+    run([...viteCmd.argv, "build"], { cwd: root, shell: viteCmd.shell });
     const distDir = resolve(root, conf.frontend?.dist ?? "dist");
     const html = inlineDist(distDir);
     console.log(`janela: frontend inlined (${(Buffer.byteLength(html) / 1024).toFixed(0)} kB)`);
@@ -274,8 +278,6 @@ function webview2Include(cacheDir) {
 // Everything below is simulator-only: a device build additionally needs a
 // signing identity and a provisioning profile, which is its own project.
 
-const IOS_MIN_VERSION = "15.0";
-const IOS_PREFIX = "jl_";
 
 function iosDeviceOrFail(name) {
   const json = capture(["xcrun", "simctl", "list", "devices", "available", "--json"]);
@@ -296,86 +298,9 @@ function iosDeviceOrFail(name) {
   return pick;
 }
 
-function iosConf(conf) {
-  const ios = conf.ios ?? {};
-  return {
-    identifier: ios.identifier ?? conf.identifier,
-    displayName: ios.displayName ?? conf.window?.title ?? conf.name,
-    minimumVersion: String(ios.minimumVersion ?? IOS_MIN_VERSION),
-    device: ios.device ?? null,
-  };
-}
-
 // The library profile: one export carries every command, so a project's own
 // commands need no ABI of their own. `janelaEmit` is the reverse channel the
 // shell registers before init.
-function libraryProfile() {
-  return {
-    profile_format: 1,
-    name: "janela",
-    entry: "./entry.ts",
-    emission: "llvm",
-    abi: {
-      prefix: IOS_PREFIX,
-      init_symbol: `${IOS_PREFIX}init`,
-      sink_register_symbol: `${IOS_PREFIX}set_panic_sink`,
-      collect_symbol: `${IOS_PREFIX}collect`,
-      result_reset_symbol: `${IOS_PREFIX}reset`,
-      callback_register_symbol: `${IOS_PREFIX}set_callback`,
-    },
-    exports: [
-      {
-        export: "handleInvoke",
-        symbol: `${IOS_PREFIX}handle_invoke`,
-        params: ["string", "string"],
-        returns: "string",
-      },
-      {
-        export: "indexHtml",
-        symbol: `${IOS_PREFIX}index_html`,
-        params: [],
-        returns: "string",
-      },
-      // The shell calls these back on the main queue when work it owns comes
-      // due. They are the mirror of the desktop shim's wv_on_timer: the
-      // library parks a continuation under an id and is re-entered with it.
-      {
-        export: "onTimer",
-        symbol: `${IOS_PREFIX}on_timer`,
-        params: ["f64"],
-        returns: "void",
-      },
-      {
-        export: "onFsDone",
-        symbol: `${IOS_PREFIX}on_fs_done`,
-        params: ["f64", "bool", "string"],
-        returns: "void",
-      },
-      // Deliberately its own export rather than reusing onFsDone, whose
-      // signature would fit: a dialog result arriving through the file-I/O
-      // path would read as a bug for as long as the code lived.
-      {
-        export: "onDialogDone",
-        symbol: `${IOS_PREFIX}on_dialog_done`,
-        params: ["f64", "bool", "string"],
-        returns: "void",
-      },
-    ],
-    // TS -> shell. A channel handler must never re-enter the library (see
-    // upstream #263: violations silently appear to work), so every one of
-    // these only records the request; the shell acts on its own queue and
-    // re-enters through an export above on a later turn.
-    callbacks: [
-      { name: "janelaEmit", params: ["string", "string"], returns: "void" },
-      { name: "hostSchedule", params: ["f64", "f64"], returns: "void" },
-      { name: "hostSettle", params: ["f64", "string"], returns: "void" },
-      { name: "hostReadFile", params: ["f64", "string"], returns: "void" },
-      { name: "hostWriteFile", params: ["f64", "string", "string"], returns: "void" },
-      { name: "hostOpenDialog", params: ["f64", "string"], returns: "void" },
-    ],
-  };
-}
-
 function iosPlist(conf, iconFiles = []) {
   const ios = iosConf(conf);
   // The asset-catalogue route needs actool; the CFBundleIconFiles list is the
@@ -498,34 +423,11 @@ async function devIos(root) {
 // backend needs a companion class because android.webkit.WebView is a Java API
 // and native code cannot define a class to receive its callbacks.
 
-const ANDROID_MIN_SDK = 26;
-const ANDROID_TARGET_SDK = 34;
-const ANDROID_ABI = "arm64-v8a";
 
 /// Android package names are Java package names: dot-separated identifiers,
 /// so no hyphens. A janela project may be called `my-app`, which makes the
 /// default identifier `dev.janela.my-app` — legal everywhere else and not
 /// here, so each segment is coerced rather than failing the build.
-function androidPackage(id) {
-  return id
-    .split(".")
-    .map((seg) => {
-      const cleaned = seg.replace(/[^A-Za-z0-9_]/g, "_");
-      return /^[A-Za-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
-    })
-    .join(".");
-}
-
-function androidConf(conf) {
-  const a = conf.android ?? {};
-  return {
-    applicationId: androidPackage(a.applicationId ?? a.identifier ?? conf.identifier),
-    label: a.label ?? conf.window?.title ?? conf.name,
-    minSdk: String(a.minSdk ?? ANDROID_MIN_SDK),
-    device: a.device ?? null,
-  };
-}
-
 /// The SDK pieces an Android build needs, or a message saying which is absent.
 function androidSdk() {
   const home =
@@ -835,128 +737,6 @@ function buildShim(cacheDir) {
 
 // ---- 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"),
-    STR("wvReply", "wv_reply"),
-    // Retained handlers (format 4): registered once, valid for the app's
-    // lifetime, so wv_run is a plain blocking call. The request rides in as a
-    // `string` param (format 3) rather than a byte-at-a-time drain.
-    {
-      name: "wvOnInvoke", symbol: "wv_on_invoke",
-      params: [
-        "i32",
-        { callback: { id: "inv", params: ["string", { context: "inv" }], returns: "i32", lifetime: "retained" } },
-        { context: "inv" },
-      ],
-      returns: "i32",
-    },
-    {
-      name: "wvOnTimer", symbol: "wv_on_timer",
-      params: [
-        "i32",
-        { callback: { id: "timer", params: ["i32", { context: "timer" }], returns: "void", lifetime: "retained" } },
-        { context: "timer" },
-      ],
-      returns: "i32",
-    },
-    { name: "wvRun", symbol: "wv_run", params: ["i32"], returns: "i32" },
-    { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
-    // async: the held-reply table (deferred returns) plus shell-owned
-    // scheduling — TS parks a continuation id, the shell calls it back due.
-    { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
-    { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
-    { name: "wvSchedule", symbol: "wv_schedule", params: ["i32", "i32", "i32"], returns: "i32" },
-    // async file I/O: the blocking syscall runs on a shim worker thread
-    { name: "wvFsRead", symbol: "wv_fs_read", params: ["i32", "string"], returns: "i32" },
-    { name: "wvFsWrite", symbol: "wv_fs_write", params: ["i32", "string", "string"], returns: "i32" },
-    // Job accessors, shared by file I/O and dialogs: both are work whose
-    // answer cannot be produced during the FFI call that starts it.
-    { name: "wvJobStatus", symbol: "wv_job_status", params: ["i32", "i32"], returns: "i32" },
-    { name: "wvJobSize", symbol: "wv_job_size", params: ["i32", "i32"], returns: "f64" },
-    {
-      // One slice per call, so a large payload decodes across several UI turns
-      // instead of stalling on all of it at once. Returns the bytes covered.
-      name: "wvJobTakeAt", symbol: "wv_job_take_at",
-      params: [
-        "i32", "i32", "f64", "f64",
-        { callback: { id: "sink", params: ["string", { context: "sink" }], returns: "void", lifetime: "call" } },
-        { context: "sink" },
-      ],
-      returns: "f64",
-    },
-    { name: "wvJobFree", symbol: "wv_job_free", params: ["i32", "i32"], returns: "i32" },
-    // Native dialogs: the modal runs on a later UI-thread turn, so asking for
-    // one never blocks the invoke that asked. Options ride as plain params
-    // (kind, flags, title, defaultPath, defaultName, filters).
-    {
-      name: "wvDialog", symbol: "wv_dialog",
-      params: ["i32", "i32", "i32", "string", "string", "string", "string"],
-      returns: "i32",
-    },
-    { name: "wvSetFullscreen", symbol: "wv_set_fullscreen", params: ["i32", "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: 4,
-      functions,
-      libraries: [shimLib],
-      system_libraries: [
-        "c++", "pthread",
-        "ole32", "oleaut32", "shlwapi", "shell32", "user32", "version", "gdi32",
-        // GetOpenFileNameW / GetSaveFileNameW for the native file dialogs.
-        "comdlg32",
-      ],
-    };
-  }
-
-  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: 4,
-      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: 4,
-    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",
-    ],
-  };
-}
 
 // ---- Windows subsystem ------------------------------------------------------
 
@@ -972,34 +752,16 @@ function ffiManifest(shimLib) {
 // the loader whether to allocate a console. Every offset is checked before
 // anything is written, and a file that does not look like a console-subsystem
 // PE is left alone.
-const IMAGE_SUBSYSTEM_WINDOWS_GUI = 2;
-const IMAGE_SUBSYSTEM_WINDOWS_CUI = 3;
 
 function makeGuiSubsystem(exePath) {
-  const buf = readFileSync(exePath);
-  if (buf.length < 0x40 || buf.readUInt16LE(0) !== 0x5a4d) {
-    fail(`${exePath} is not a PE image (no MZ header)`);
+  let result;
+  try {
+    result = patchPeSubsystem(readFileSync(exePath));
+  } catch (e) {
+    if (e instanceof PeError) fail(`${exePath} ${e.message}`);
+    throw e;
   }
-  const peOff = buf.readUInt32LE(0x3c);
-  if (peOff + 24 > buf.length || buf.readUInt32LE(peOff) !== 0x00004550) {
-    fail(`${exePath} has no PE signature at ${peOff}`);
-  }
-  // Optional header starts after the 4-byte signature and 20-byte COFF header;
-  // Subsystem sits at +68 in both PE32 (0x10b) and PE32+ (0x20b).
-  const optOff = peOff + 24;
-  const magic = buf.readUInt16LE(optOff);
-  if (magic !== 0x10b && magic !== 0x20b) {
-    fail(`${exePath} has an unrecognised optional header magic 0x${magic.toString(16)}`);
-  }
-  const subOff = optOff + 68;
-  if (subOff + 2 > buf.length) fail(`${exePath} is truncated before its Subsystem field`);
-  const current = buf.readUInt16LE(subOff);
-  if (current === IMAGE_SUBSYSTEM_WINDOWS_GUI) return;
-  if (current !== IMAGE_SUBSYSTEM_WINDOWS_CUI) {
-    fail(`${exePath} has an unexpected subsystem ${current}; refusing to rewrite it`);
-  }
-  buf.writeUInt16LE(IMAGE_SUBSYSTEM_WINDOWS_GUI, subOff);
-  writeFileSync(exePath, buf);
+  if (result.patched) writeFileSync(exePath, result.buf);
 }
 
 // ---- build ----------------------------------------------------------------
@@ -1187,10 +949,7 @@ function build(root, { devUrl = null, gui = true, target = "desktop" } = {}) {
   // as well.
   writeFileSync(
     join(buildDir, "main.ts"),
-    readFileSync(mainSrc, "utf8").replace(
-      /(\bfrom\s*)(['"])janela\/host\2/g,
-      "$1$2./janela$2",
-    ),
+    rewriteHostSpecifier(readFileSync(mainSrc, "utf8")),
   );
 
   const html = frontendHtml(root, conf, devUrl);
@@ -1261,7 +1020,12 @@ function build(root, { devUrl = null, gui = true, target = "desktop" } = {}) {
   if (ios) return buildIos(root, conf, buildDir, outDir);
   if (android) return buildAndroid(root, conf, buildDir, outDir);
 
-  writeFileSync(join(buildDir, "janela.ffi.json"), JSON.stringify(ffiManifest(shimLib), null, 2) + "\n");
+  writeFileSync(join(buildDir, "janela.ffi.json"), JSON.stringify(ffiManifest(shimLib, {
+      macSdkPath:
+        process.platform === "darwin"
+          ? capture(["xcrun", "--sdk", "macosx", "--show-sdk-path"])
+          : null,
+    }), null, 2) + "\n");
 
   console.log("janela: compiling TypeScript to a native binary");
   // An explicit --out is used verbatim, so the PE suffix is ours to add.
@@ -1374,20 +1138,9 @@ function copyTemplate(from, to, name) {
 // allowed because people type them and every downstream use accepts them —
 // Android application ids in particular *prefer* them, since a Java package
 // segment cannot contain a hyphen (see androidApplicationId).
-const NAME_RE = /^[a-z][a-z0-9_-]*$/;
 
 // Best-effort repair of a rejected name, so the error can suggest something
 // that would have worked instead of only stating the rule.
-function suggestName(raw) {
-  const s = String(raw)
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/^[^a-z]+/, "")
-    .replace(/-{2,}/g, "-")
-    .replace(/[-_]+$/, "");
-  return NAME_RE.test(s) ? s : "";
-}
-
 function init(name, template) {
   if (!name) {
     fail(
@@ -1484,11 +1237,11 @@ async function dev(root) {
     const port = await freePort();
     devUrl = `http://localhost:${port}/`;
     console.log(`janela: starting the vite dev server on ${devUrl}`);
-    vite = spawn(viteBin(root), ["--port", String(port), "--strictPort"], {
+    const viteCmd = viteCommand(root);
+    vite = spawn(viteCmd.argv[0], [...viteCmd.argv.slice(1), "--port", String(port), "--strictPort"], {
       cwd: root,
       stdio: "inherit",
-      // Windows resolves .cmd shims through the shell.
-      shell: process.platform === "win32",
+      shell: viteCmd.shell,
     });
     const stop = () => { if (vite && vite.exitCode === null) vite.kill(); };
     process.on("exit", stop);

package/bin/lib.mjs

@@ -0,0 +1,347 @@
+/**
+ * Pure helpers shared by the CLI and its tests.
+ *
+ * `bin/janela.mjs` is build orchestration: it shells out, writes files and
+ * exits. The decisions inside it — how a name is validated, how a config's
+ * defaults fall back, which symbols an FFI manifest must declare, which bytes
+ * of a PE may be rewritten — are pure, and a wrong answer from any of them
+ * fails quietly rather than loudly: a missing FFI declaration makes the
+ * runtime fail to link, and a mis-coerced Android id is rejected by aapt2
+ * only at package time.
+ *
+ * So they live here, where a test can call them directly. Nothing in this
+ * file touches the filesystem, the network or a subprocess.
+ */
+
+import { join } from "node:path";
+
+// ---- project names ---------------------------------------------------------
+
+export const NAME_RE = /^[a-z][a-z0-9_-]*$/;
+
+export const MIME = {
+  ".css": "text/css", ".js": "text/javascript", ".json": "application/json",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif",
+  ".svg": "image/svg+xml", ".ico": "image/x-icon",
+  ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+  ".mp3": "audio/mpeg", ".mp4": "video/mp4", ".webm": "video/webm",
+};
+export const STR = (name, symbol) => ({ name, symbol, params: ["i32", "string"], returns: "i32" });
+export const IOS_MIN_VERSION = "15.0";
+export const IOS_PREFIX = "jl_";
+export const ANDROID_MIN_SDK = 26;
+export const ANDROID_TARGET_SDK = 34;
+export const ANDROID_ABI = "arm64-v8a";
+export const IMAGE_SUBSYSTEM_WINDOWS_GUI = 2;
+export const IMAGE_SUBSYSTEM_WINDOWS_CUI = 3;
+
+export function suggestName(raw) {
+  const s = String(raw)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^[^a-z]+/, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/[-_]+$/, "");
+  return NAME_RE.test(s) ? s : "";
+}
+
+export function androidPackage(id) {
+  return id
+    .split(".")
+    .map((seg) => {
+      const cleaned = seg.replace(/[^A-Za-z0-9_]/g, "_");
+      return /^[A-Za-z_]/.test(cleaned) ? cleaned : `_${cleaned}`;
+    })
+    .join(".");
+}
+
+export function androidConf(conf) {
+  const a = conf.android ?? {};
+  return {
+    applicationId: androidPackage(a.applicationId ?? a.identifier ?? conf.identifier),
+    label: a.label ?? conf.window?.title ?? conf.name,
+    minSdk: String(a.minSdk ?? ANDROID_MIN_SDK),
+    device: a.device ?? null,
+  };
+}
+
+export function iosConf(conf) {
+  const ios = conf.ios ?? {};
+  return {
+    identifier: ios.identifier ?? conf.identifier,
+    displayName: ios.displayName ?? conf.window?.title ?? conf.name,
+    minimumVersion: String(ios.minimumVersion ?? IOS_MIN_VERSION),
+    device: ios.device ?? null,
+  };
+}
+
+export function libraryProfile() {
+  return {
+    profile_format: 1,
+    name: "janela",
+    entry: "./entry.ts",
+    emission: "llvm",
+    abi: {
+      prefix: IOS_PREFIX,
+      init_symbol: `${IOS_PREFIX}init`,
+      sink_register_symbol: `${IOS_PREFIX}set_panic_sink`,
+      collect_symbol: `${IOS_PREFIX}collect`,
+      result_reset_symbol: `${IOS_PREFIX}reset`,
+      callback_register_symbol: `${IOS_PREFIX}set_callback`,
+    },
+    exports: [
+      {
+        export: "handleInvoke",
+        symbol: `${IOS_PREFIX}handle_invoke`,
+        params: ["string", "string"],
+        returns: "string",
+      },
+      {
+        export: "indexHtml",
+        symbol: `${IOS_PREFIX}index_html`,
+        params: [],
+        returns: "string",
+      },
+      // The shell calls these back on the main queue when work it owns comes
+      // due. They are the mirror of the desktop shim's wv_on_timer: the
+      // library parks a continuation under an id and is re-entered with it.
+      {
+        export: "onTimer",
+        symbol: `${IOS_PREFIX}on_timer`,
+        params: ["f64"],
+        returns: "void",
+      },
+      {
+        export: "onFsDone",
+        symbol: `${IOS_PREFIX}on_fs_done`,
+        params: ["f64", "bool", "string"],
+        returns: "void",
+      },
+      // Deliberately its own export rather than reusing onFsDone, whose
+      // signature would fit: a dialog result arriving through the file-I/O
+      // path would read as a bug for as long as the code lived.
+      {
+        export: "onDialogDone",
+        symbol: `${IOS_PREFIX}on_dialog_done`,
+        params: ["f64", "bool", "string"],
+        returns: "void",
+      },
+    ],
+    // TS -> shell. A channel handler must never re-enter the library (see
+    // upstream #263: violations silently appear to work), so every one of
+    // these only records the request; the shell acts on its own queue and
+    // re-enters through an export above on a later turn.
+    callbacks: [
+      { name: "janelaEmit", params: ["string", "string"], returns: "void" },
+      { name: "hostSchedule", params: ["f64", "f64"], returns: "void" },
+      { name: "hostSettle", params: ["f64", "string"], returns: "void" },
+      { name: "hostReadFile", params: ["f64", "string"], returns: "void" },
+      { name: "hostWriteFile", params: ["f64", "string", "string"], returns: "void" },
+      { name: "hostOpenDialog", params: ["f64", "string"], returns: "void" },
+    ],
+  };
+}
+
+export function mimeFor(p) {
+  const dot = p.lastIndexOf(".");
+  return (dot < 0 ? null : MIME[p.slice(dot).toLowerCase()]) ?? "application/octet-stream";
+}
+
+/**
+ * The FFI manifest a desktop build hands to scriptc: every shim symbol the
+ * runtime calls, plus the per-platform link inputs.
+ *
+ * `platform` and `macSdkPath` are parameters rather than ambient lookups so
+ * that every branch is reachable from any host — a manifest that silently
+ * loses a declaration fails at link time, on one platform, which is the worst
+ * place to find out.
+ */
+export function ffiManifest(shimLib, { platform = process.platform, macSdkPath = null } = {}) {
+  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"),
+    STR("wvReply", "wv_reply"),
+    // Retained handlers (format 4): registered once, valid for the app's
+    // lifetime, so wv_run is a plain blocking call. The request rides in as a
+    // `string` param (format 3) rather than a byte-at-a-time drain.
+    {
+      name: "wvOnInvoke", symbol: "wv_on_invoke",
+      params: [
+        "i32",
+        { callback: { id: "inv", params: ["string", { context: "inv" }], returns: "i32", lifetime: "retained" } },
+        { context: "inv" },
+      ],
+      returns: "i32",
+    },
+    {
+      name: "wvOnTimer", symbol: "wv_on_timer",
+      params: [
+        "i32",
+        { callback: { id: "timer", params: ["i32", { context: "timer" }], returns: "void", lifetime: "retained" } },
+        { context: "timer" },
+      ],
+      returns: "i32",
+    },
+    { name: "wvRun", symbol: "wv_run", params: ["i32"], returns: "i32" },
+    { name: "wvTerminate", symbol: "wv_terminate", params: ["i32"], returns: "i32" },
+    // async: the held-reply table (deferred returns) plus shell-owned
+    // scheduling — TS parks a continuation id, the shell calls it back due.
+    { name: "wvDefer", symbol: "wv_defer", params: ["i32"], returns: "i32" },
+    { name: "wvResolve", symbol: "wv_resolve", params: ["i32", "i32", "i32"], returns: "i32" },
+    { name: "wvSchedule", symbol: "wv_schedule", params: ["i32", "i32", "i32"], returns: "i32" },
+    // async file I/O: the blocking syscall runs on a shim worker thread
+    { name: "wvFsRead", symbol: "wv_fs_read", params: ["i32", "string"], returns: "i32" },
+    { name: "wvFsWrite", symbol: "wv_fs_write", params: ["i32", "string", "string"], returns: "i32" },
+    // Job accessors, shared by file I/O and dialogs: both are work whose
+    // answer cannot be produced during the FFI call that starts it.
+    { name: "wvJobStatus", symbol: "wv_job_status", params: ["i32", "i32"], returns: "i32" },
+    { name: "wvJobSize", symbol: "wv_job_size", params: ["i32", "i32"], returns: "f64" },
+    {
+      // One slice per call, so a large payload decodes across several UI turns
+      // instead of stalling on all of it at once. Returns the bytes covered.
+      name: "wvJobTakeAt", symbol: "wv_job_take_at",
+      params: [
+        "i32", "i32", "f64", "f64",
+        { callback: { id: "sink", params: ["string", { context: "sink" }], returns: "void", lifetime: "call" } },
+        { context: "sink" },
+      ],
+      returns: "f64",
+    },
+    { name: "wvJobFree", symbol: "wv_job_free", params: ["i32", "i32"], returns: "i32" },
+    // Native dialogs: the modal runs on a later UI-thread turn, so asking for
+    // one never blocks the invoke that asked. Options ride as plain params
+    // (kind, flags, title, defaultPath, defaultName, filters).
+    {
+      name: "wvDialog", symbol: "wv_dialog",
+      params: ["i32", "i32", "i32", "string", "string", "string", "string"],
+      returns: "i32",
+    },
+    { name: "wvSetFullscreen", symbol: "wv_set_fullscreen", params: ["i32", "i32"], returns: "i32" },
+  ];
+
+  if (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: 4,
+      functions,
+      libraries: [shimLib],
+      system_libraries: [
+        "c++", "pthread",
+        "ole32", "oleaut32", "shlwapi", "shell32", "user32", "version", "gdi32",
+        // GetOpenFileNameW / GetSaveFileNameW for the native file dialogs.
+        "comdlg32",
+      ],
+    };
+  }
+
+  if (platform === "darwin") {
+    // scriptc has no -framework support, but `libraries` entries are passed to
+    // the link as plain input files and ld64 accepts .tbd stubs.
+    if (!macSdkPath) throw new Error("ffiManifest: macSdkPath is required on darwin");
+    const sdk = macSdkPath;
+    return {
+      ffi_format: 4,
+      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: 4,
+    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",
+    ],
+  };
+}
+// ---- host specifier rewrite -------------------------------------------------
+
+/**
+ * Rewrite a project's `from "janela/host"` to the runtime copy the CLI places
+ * beside it in `.janela/build/`.
+ *
+ * A project imports the package specifier so that it resolves in an editor
+ * against the installed package; the build compiles against the local copy
+ * instead, which keeps it static (no node_modules resolution) and keeps
+ * working once "janela/host" exports values and not only types.
+ *
+ * Deliberately narrow: only a specifier in `from` position, only that exact
+ * module, either quote style. A mention inside a comment or a longer
+ * specifier such as "janela/host-extras" is left alone.
+ */
+export function rewriteHostSpecifier(src) {
+  return src.replace(/(\bfrom\s*)(['"])janela\/host\2/g, "$1$2./janela$2");
+}
+
+// ---- Windows subsystem ------------------------------------------------------
+
+/** A PE the patcher refused to touch, with `code` naming the reason. */
+export class PeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * Flip a console-subsystem PE to the GUI subsystem, in place, on a copy of
+ * the caller's buffer.
+ *
+ * Returns `{ patched: false }` when the image is already GUI, or
+ * `{ patched: true, buf }` with the rewritten bytes. Anything that does not
+ * look like the console-subsystem PE we just linked throws a `PeError`
+ * instead of being modified — the whole point is to touch exactly one field
+ * of exactly one shape of file.
+ */
+export function patchPeSubsystem(input) {
+  const buf = Buffer.from(input);
+  if (buf.length < 0x40 || buf.readUInt16LE(0) !== 0x5a4d) {
+    throw new PeError("no-mz", "not a PE image (no MZ header)");
+  }
+  const peOff = buf.readUInt32LE(0x3c);
+  if (peOff + 24 > buf.length || buf.readUInt32LE(peOff) !== 0x00004550) {
+    throw new PeError("no-pe", `no PE signature at ${peOff}`);
+  }
+  // Optional header starts after the 4-byte signature and 20-byte COFF header;
+  // Subsystem sits at +68 in both PE32 (0x10b) and PE32+ (0x20b).
+  const optOff = peOff + 24;
+  const magic = buf.readUInt16LE(optOff);
+  if (magic !== 0x10b && magic !== 0x20b) {
+    throw new PeError("bad-magic", `unrecognised optional header magic 0x${magic.toString(16)}`);
+  }
+  const subOff = optOff + 68;
+  if (subOff + 2 > buf.length) {
+    throw new PeError("truncated", "truncated before its Subsystem field");
+  }
+  const current = buf.readUInt16LE(subOff);
+  if (current === IMAGE_SUBSYSTEM_WINDOWS_GUI) return { patched: false };
+  if (current !== IMAGE_SUBSYSTEM_WINDOWS_CUI) {
+    throw new PeError("unexpected-subsystem", `unexpected subsystem ${current}; refusing to rewrite it`);
+  }
+  buf.writeUInt16LE(IMAGE_SUBSYSTEM_WINDOWS_GUI, subOff);
+  return { patched: true, buf };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -56,5 +56,13 @@
     "templates/",
     "vendor-webview/core/include/",
     "vendor-webview/LICENSE"
-  ]
+  ],
+  "scripts": {
+    "test": "npm run test:unit && npm run test:types",
+    "test:unit": "node --test test/unit/*.test.mjs",
+    "test:types": "node test/types/run.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }

package/shim/android/app.cc

@@ -328,6 +328,15 @@ void finish_fs(double id, bool ok, std::string payload) {
 void host_read_file(void *, double id, const char *path, size_t path_len) {
   std::string p = resolve_path(std::string(path, path_len));
   std::thread([id, p] {
+    // As on iOS: a directory opens as an ifstream and reads as empty, which
+    // would report success with no content. Desktop answers EISDIR; keep the
+    // message identical across platforms.
+    struct stat st;
+    if (::stat(p.c_str(), &st) == 0 && S_ISDIR(st.st_mode)) {
+      finish_fs(id, false,
+                "EISDIR: illegal operation on a directory, read '" + p + "'");
+      return;
+    }
     std::ifstream in(p, std::ios::binary);
     if (!in) {
       finish_fs(id, false,

package/shim/ios/app.cc

@@ -277,6 +277,16 @@ void finish_fs(double id, bool ok, std::string payload) {
 void host_read_file(void *, double id, const char *path, size_t path_len) {
   std::string p = resolve_path(std::string(path, path_len));
   dispatch_async(fs_queue(), ^{
+    // A directory opens cleanly as an ifstream on Apple platforms and then
+    // reads as empty, so without this check readFileAsync would report
+    // success with no content. Desktop already answers EISDIR here; the
+    // message is kept identical so app code can treat the platforms alike.
+    struct stat st;
+    if (::stat(p.c_str(), &st) == 0 && S_ISDIR(st.st_mode)) {
+      finish_fs(id, false,
+                "EISDIR: illegal operation on a directory, read '" + p + "'");
+      return;
+    }
     std::ifstream in(p, std::ios::binary);
     if (!in) {
       finish_fs(id, false, "ENOENT: no such file or directory, open '" + p + "'");