janela 0.13.0 → 0.14.0

package/README.md

@@ -5,8 +5,11 @@
 Desktop and mobile 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). Binaries come out
-around 400–500 KB, with no bundled browser and no bundled runtime.
+[webview/webview](https://github.com/webview/webview). A desktop binary comes
+out around 200–400 KB — 191 KB for the smallest template — with no bundled
+browser and no bundled runtime; iOS and Android bundles land around
+384–578 KB. Per-template figures are in
+[docs/frontend.md](../../docs/frontend.md).
 
 Five targets, one runtime — the same `main.ts`, the same typed contract and the
 same frontend build for each:
@@ -542,7 +545,7 @@ app.command("add", (args) => {
 Mechanically: drop the `JSON.parse(argsJson)` (cast `args` instead), drop
 every `JSON.stringify` around a result, `resolve`/`reject`/`emit` payload, and
 return nothing at all where you used to return `"null"`. Requires Node 24 to
-build (scriptc 0.0.35's floor).
+build (scriptc 0.0.36's floor).
 
 ## What the CLI hides
 
@@ -559,10 +562,6 @@ no `-framework` support) and the binary is wrapped into an ad-hoc-signed
   the boundary, so anything that survives `JSON.stringify`/`JSON.parse` round
   trips (including full Unicode). `args` is typed `unknown` — cast it to the
   shape you expect.
-- 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. Host code is single-threaded: a synchronous
   command blocks the UI while it runs — use `commandAsync` + `defer`/`sleep`
   (see "Async commands") for anything slow.
@@ -583,8 +582,10 @@ It is **simulator-only** so far — device builds and code signing are not
 wired up yet. Commands, the typed
 contract, events, Vite frontends, async commands (`commandAsync`, `defer`,
 `sleep`) and file I/O all work the same as on desktop — the shell owns the
-clock and the file queue on both. File dialogs are not on iOS yet and report
-clearly when called; window control is a no-op there by nature. See
+clock and the file queue on both. `openFileDialog` works as of 0.13.0 — the
+picked file is copied into the app container and that path returned, so
+`readFileAsync` opens it exactly as on desktop. `saveFileDialog` reports
+clearly when called, and window control is a no-op there by nature. See
 [docs/ios.md](../../docs/ios.md).
 
 ## Android
@@ -615,11 +616,18 @@ The design notes and scriptc findings behind it are in
 [docs/findings.md](../../docs/findings.md), with per-platform notes in
 [docs/ios.md](../../docs/ios.md) and [docs/android.md](../../docs/android.md).
 
-Not yet: native dialogs and window control on mobile; device builds and code
-signing; icons, installers and notarization; async commands that run in
-parallel (host code is single-threaded, so `commandAsync` interleaves and a
-CPU-bound handler still needs slicing); an async HTTP client; tray icons and
-menus; multi-window; directory picking on Windows; and `app.center()`.
+Not yet: `saveFileDialog` and window control on mobile (both deliberate —
+mobile "save" means exporting a file that already exists, which the desktop
+signature cannot express, and window geometry is meaningless on a phone);
+iOS device builds and code signing; installers and notarization; async
+commands that run in parallel (host code is single-threaded, so
+`commandAsync` interleaves and a CPU-bound handler still needs slicing); an
+async HTTP client; tray icons and menus; multi-window; directory picking on
+Windows and iOS; and `app.center()`.
+
+`openFileDialog` **does** work on iOS and Android as of 0.13.0 — a picked
+file is copied into the app container and that path returned, so
+`readFileAsync` opens it exactly as on desktop.
 
 ## Releasing
 

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);
@@ -1235,7 +994,7 @@ function build(root, { devUrl = null, gui = true, target = "desktop" } = {}) {
       `}\n`
     : `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
       `setup(app);\n` +
-      `const rc = app.run(INDEX_HTML) + 0;\n` +
+      `const rc = app.run(INDEX_HTML);\n` +
       `console.log("[janela] run returned", rc);\n`;
 
   writeFileSync(
@@ -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.14.0",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "scriptc": "0.0.35"
+    "scriptc": "0.0.36"
   },
   "license": "MIT",
   "author": "Mateus Lage",
@@ -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/runtime/janela.ts

@@ -4,11 +4,6 @@
 // (name, argsJson) envelope, dispatched to handlers registered on the app
 // object. Handlers see decoded values — the runtime owns JSON at the boundary.
 // 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 miscompiles a bare FFI call used as a complete
-// initializer/assignment RHS — still true in 0.0.35, and reported upstream as
-// vercel-labs/scriptc#21. Any enclosing expression is the workaround.
 
 declare function wvCreate(debug: number): number;
 declare function wvSetTitle(h: number, title: string): number;
@@ -202,7 +197,7 @@ export class JanelaAppImpl<
   drainSize: number[] = [];
 
   constructor(cfg: WindowConfig) {
-    const h = wvCreate(0) + 0;
+    const h = wvCreate(0);
     this.handle = h;
     wvSetTitle(h, cfg.title);
     wvSetSize(h, cfg.width, cfg.height, 0);
@@ -221,9 +216,7 @@ export class JanelaAppImpl<
     this.contIds.push(id);
     this.contFns.push(fn);
     const delay = ms > 0 ? ms : 0;
-    // `+ 0` per the note at the top of this file: a bare FFI call is not safe
-    // in every position, and this one is silently dropped without it.
-    const rc = wvSchedule(this.handle, id, delay) + 0;
+    const rc = wvSchedule(this.handle, id, delay);
     if (rc < 0) console.log("[janela] could not schedule continuation", id);
   }
 
@@ -254,14 +247,14 @@ export class JanelaAppImpl<
    */
   drainSome(): void {
     if (this.drainIds.length === 0) return;
-    const started = Date.now() + 0;
+    const started = Date.now();
 
     while (this.drainIds.length > 0) {
       let chunk = "";
       const taken =
         wvJobTakeAt(this.handle, this.drainIds[0], this.drainOff[0], DRAIN_SLICE, (text) => {
           chunk = text;
-        }) + 0;
+        });
 
       // A negative count means the job vanished; treat the payload as final
       // rather than spinning on it forever.
@@ -334,7 +327,7 @@ export class JanelaAppImpl<
       const doneCbs: FsCallback[] = [];
       const doneOk: boolean[] = [];
       for (let i = 0; i < this.jobIds.length; i++) {
-        const st = wvJobStatus(this.handle, this.jobIds[i]) + 0;
+        const st = wvJobStatus(this.handle, this.jobIds[i]);
         if (st === JOB_PENDING) {
           keptIds.push(this.jobIds[i]);
           keptCbs.push(this.jobCbs[i]);
@@ -355,7 +348,7 @@ export class JanelaAppImpl<
         this.drainOk.push(doneOk[i]);
         this.drainParts.push([]);
         this.drainOff.push(0);
-        this.drainSize.push(wvJobSize(this.handle, doneIds[i]) + 0);
+        this.drainSize.push(wvJobSize(this.handle, doneIds[i]));
       }
     }
 
@@ -381,7 +374,7 @@ export class JanelaAppImpl<
       defaultPath === undefined ? "" : defaultPath,
       defaultName === undefined ? "" : defaultName,
       encodeFilters(filters),
-    ) + 0;
+    );
     if (id < 0) {
       this.defer(() => cb(null, "EAGAIN: could not open a dialog"));
       return;
@@ -452,7 +445,7 @@ export class JanelaAppImpl<
    * worker thread; the callback lands on the UI thread on a later turn.
    */
   readFileAsync(path: string, cb: FsCallback): void {
-    const id = wvFsRead(this.handle, path) + 0;
+    const id = wvFsRead(this.handle, path);
     if (id < 0) {
       this.defer(() => cb("EAGAIN: could not start a read of '" + path + "'", ""));
       return;
@@ -463,7 +456,7 @@ export class JanelaAppImpl<
 
   /** Write a file without blocking the window; cb(null) on success. */
   writeFileAsync(path: string, data: string, cb: (err: string | null) => void): void {
-    const id = wvFsWrite(this.handle, path, data) + 0;
+    const id = wvFsWrite(this.handle, path, data);
     if (id < 0) {
       this.defer(() => cb("EAGAIN: could not start a write of '" + path + "'"));
       return;
@@ -555,7 +548,7 @@ export class JanelaAppImpl<
           // 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;
+          const id = wvDefer(h);
           if (id < 0) {
             wvReply(h, encode("cannot defer command: " + cmd));
             return 1;
@@ -579,7 +572,7 @@ export class JanelaAppImpl<
 
     wvBind(h, "__invoke");
     wvSetHtml(h, html);
-    const rc = wvRun(h) + 0;
+    const rc = wvRun(h);
     return rc;
   }
 }

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 + "'");

package/templates/main.ts

@@ -3,10 +3,6 @@
 // Register commands here; the page calls them with `await janela.invoke(name, args)`.
 // Handlers take the arguments as a value and return a value — the runtime owns
 // JSON at the boundary, so there is no parsing or stringifying to do here.
-//
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
 
 import type { JanelaApp } from "janela/host";
 

package/templates/react/files/src-host/main.ts

@@ -6,11 +6,8 @@
 // names, argument shapes, results and event payloads — with no code
 // generation and nothing to keep in sync.
 //
-// Two gotchas inherited from scriptc:
-//   - never use a bare FFI-backed call as a complete variable initializer;
-//     wrap it in any expression (`+ 0`);
-//   - a command that returns nothing is declared `() => void` and its handler
-//     returns `null`; every command answers the page's promise with a value.
+// A command that returns nothing is declared `() => void` and its handler
+// returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 

package/templates/solid/files/src-host/main.ts

@@ -6,11 +6,8 @@
 // names, argument shapes, results and event payloads — with no code
 // generation and nothing to keep in sync.
 //
-// Two gotchas inherited from scriptc:
-//   - never use a bare FFI-backed call as a complete variable initializer;
-//     wrap it in any expression (`+ 0`);
-//   - a command that returns nothing is declared `() => void` and its handler
-//     returns `null`; every command answers the page's promise with a value.
+// A command that returns nothing is declared `() => void` and its handler
+// returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 

package/templates/svelte/files/src-host/main.ts

@@ -6,11 +6,8 @@
 // names, argument shapes, results and event payloads — with no code
 // generation and nothing to keep in sync.
 //
-// Two gotchas inherited from scriptc:
-//   - never use a bare FFI-backed call as a complete variable initializer;
-//     wrap it in any expression (`+ 0`);
-//   - a command that returns nothing is declared `() => void` and its handler
-//     returns `null`; every command answers the page's promise with a value.
+// A command that returns nothing is declared `() => void` and its handler
+// returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";
 

package/templates/vue/files/src-host/main.ts

@@ -6,11 +6,8 @@
 // names, argument shapes, results and event payloads — with no code
 // generation and nothing to keep in sync.
 //
-// Two gotchas inherited from scriptc:
-//   - never use a bare FFI-backed call as a complete variable initializer;
-//     wrap it in any expression (`+ 0`);
-//   - a command that returns nothing is declared `() => void` and its handler
-//     returns `null`; every command answers the page's promise with a value.
+// A command that returns nothing is declared `() => void` and its handler
+// returns `null`; every command answers the page's promise with a value.
 
 import type { JanelaApp } from "janela/host";