janela 0.16.1 → 0.17.1

package/bin/janela.mjs

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import {
   ANDROID_ABI, ANDROID_TARGET_SDK, androidConf, ffiManifest, iosConf,
   installCommand, libraryProfile, mimeFor, NAME_RE, packageManager as pmFor,
+  shimCacheKey,
   patchPeSubsystem, PeError, rewriteHostSpecifier, suggestName,
 } from "./lib.mjs";
 
@@ -730,10 +731,29 @@ function buildShim(cacheDir) {
   // part of an MSVC toolchain, and a lone object needs no archive index.
   const obj = join(cacheDir, win ? "wvshim.obj" : "wvshim.o");
   const lib = win ? obj : join(cacheDir, "libwvshim.a");
-  if (existsSync(lib) && statSync(lib).mtimeMs > statSync(src).mtimeMs) return lib;
+  const inc = `-I${join(KIT, "vendor-webview", "core", "include")}`;
+
+  // Keyed on the shim's CONTENT, not its mtime.
+  //
+  // The mtime test this replaces was wrong in the one case that matters:
+  // upgrading janela. pnpm's store is content-addressed and hard-links files
+  // into node_modules with the STORE's mtime, which is older than a cached
+  // object built minutes earlier from the previous version — so the cache
+  // looked fresh and a stale archive was reused. The symptom is a link failure
+  // naming symbols the new shim exports and the old object does not
+  // ("Undefined symbols: _wv_set_menu, _wv_on_menu"), which reads as a broken
+  // install rather than a stale cache.
+  //
+  // The version is in the key too: a shim that happens to be byte-identical
+  // across versions still gets recompiled if anything else about the build
+  // moved, which is cheap insurance against the next variant of this.
+  const key = shimCacheKey(readFileSync(src), VERSION, process.platform, inc);
+  const keyFile = join(cacheDir, "wvshim.key");
+  if (existsSync(lib) && existsSync(keyFile) && readFileSync(keyFile, "utf8") === key) {
+    return lib;
+  }
 
   console.log("janela: compiling webview shim");
-  const inc = `-I${join(KIT, "vendor-webview", "core", "include")}`;
   if (win) {
     console.log(`janela: building for ${winCcOrFail()}`);
     run([
@@ -743,6 +763,7 @@ function buildShim(cacheDir) {
       `-I${join(KIT, "vendor-webview", "compatibility", "mingw", "include")}`,
       "-DWIN32_LEAN_AND_MEAN", "-D_WIN32_WINNT=0x0601",
     ]);
+    writeFileSync(keyFile, key);
     return lib;
   }
   if (process.platform === "darwin") {
@@ -752,6 +773,7 @@ function buildShim(cacheDir) {
     run(["g++", "-c", src, "-o", obj, "-std=c++17", "-O2", inc, ...cflags]);
   }
   run(["ar", "rcs", lib, obj]);
+  writeFileSync(keyFile, key);
   return lib;
 }
 

package/bin/lib.mjs

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 /**
  * Pure helpers shared by the CLI and its tests.
  *
@@ -223,6 +224,18 @@ export function ffiManifest(shimLib, { platform = process.platform, macSdkPath =
       returns: "i32",
     },
     { name: "wvSetFullscreen", symbol: "wv_set_fullscreen", params: ["i32", "i32"], returns: "i32" },
+    STR("wvSetMenu", "wv_set_menu"),
+    // Retained like wvOnInvoke: registered once, valid until the app exits.
+    // The clicked item's id rides in as a `string` param (format 3).
+    {
+      name: "wvOnMenu", symbol: "wv_on_menu",
+      params: [
+        "i32",
+        { callback: { id: "menu", params: ["string", { context: "menu" }], returns: "i32", lifetime: "retained" } },
+        { context: "menu" },
+      ],
+      returns: "i32",
+    },
   ];
 
   if (platform === "win32") {
@@ -372,3 +385,24 @@ export function installCommand(pm) {
   if (pm === "npm") return ["npm", "install", "--no-fund", "--no-audit"];
   return [pm, "install"];
 }
+
+/**
+ * The cache key for the compiled webview shim.
+ *
+ * Keyed on the shim's CONTENT, not its mtime. The mtime test this replaced was
+ * wrong in the one case that matters — upgrading janela: pnpm's store is
+ * content-addressed and hard-links files into node_modules carrying the
+ * STORE's mtime, which is older than an object compiled minutes earlier from
+ * the previous version. The cache then looked fresh, the stale archive was
+ * reused, and the link failed naming symbols the new shim exports and the old
+ * object does not.
+ *
+ * `version` is in the key so a shim that happens to be byte-identical across
+ * releases still recompiles when anything else about the build moved.
+ */
+export function shimCacheKey(source, version, platform, includeFlag) {
+  return createHash("sha256")
+    .update(source)
+    .update(`\u0000${version}\u0000${platform}\u0000${includeFlag}`)
+    .digest("hex");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

package/runtime/janela.ts

@@ -42,6 +42,8 @@ declare function wvDialog(
   filters: string,
 ): number;
 declare function wvSetFullscreen(h: number, on: number): number;
+declare function wvSetMenu(h: number, spec: string): number;
+declare function wvOnMenu(h: number, cb: (id: string) => number): number;
 
 const JOB_PENDING = 0;
 const JOB_OK = 1;
@@ -90,6 +92,7 @@ export type {
   DialogFilter,
   Events,
   FsCallback,
+  MenuEntry,
   OpenDialogOptions,
   SaveDialogOptions,
   WindowConfig,
@@ -99,6 +102,7 @@ export type {
 // A project's `import { defineCommands } from "janela/host"` is rewritten to
 // this module by the CLI before scriptc sees it.
 export { defineCommands, defineEvents } from "./types";
+export { menuItem, menuSeparator, submenu } from "./types";
 
 import type {
   AsyncCommandHandler,
@@ -110,6 +114,7 @@ import type {
   DialogFilter,
   Events,
   FsCallback,
+  MenuEntry,
   OpenDialogOptions,
   SaveDialogOptions,
   WindowConfig,
@@ -156,6 +161,68 @@ const TIMER_JOBS = -1;
  * interface (being signature-only) never is. A class receiver works even as a
  * plain function parameter, which is what `setup(app)` is.
  */
+// ---- menu flattening ---------------------------------------------------
+//
+// The shim renders menus but parses nothing structural: the tree is flattened
+// here into one row per line with 0x1f between fields, which needs only a
+// split on the native side. Keeping the parsing in TypeScript is the whole
+// point — the native side stays a renderer.
+
+// NSEventModifierFlags.
+const MENU_SHIFT = 131072;
+const MENU_CONTROL = 262144;
+const MENU_OPTION = 524288;
+const MENU_COMMAND = 1048576;
+
+/** "CmdOrCtrl+Shift+O" -> "o<US>1179648". Unknown words are taken as the key. */
+function parseAccel(accel: string): string {
+  const parts = accel.split("+");
+  let mods = 0;
+  let key = "";
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i].toLowerCase();
+    if (p === "cmd" || p === "command" || p === "meta" || p === "super") {
+      mods = mods | MENU_COMMAND;
+    } else if (p === "cmdorctrl" || p === "commandorcontrol") {
+      // macOS is the only platform with custom menus so far, so this is
+      // Command here; the Windows and Linux renderers will read it as Control.
+      mods = mods | MENU_COMMAND;
+    } else if (p === "ctrl" || p === "control") {
+      mods = mods | MENU_CONTROL;
+    } else if (p === "alt" || p === "option") {
+      mods = mods | MENU_OPTION;
+    } else if (p === "shift") {
+      mods = mods | MENU_SHIFT;
+    } else if (p !== "") {
+      key = p;
+    }
+  }
+  return key + "\x1f" + mods;
+}
+
+/** 0x1f and newlines are the wire format's own delimiters. */
+function menuSafe(v: string): string {
+  return v.split("\x1f").join(" ").split("\n").join(" ");
+}
+
+function flattenMenu(entries: MenuEntry[], rows: string[]): void {
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.separator) {
+      rows.push("-");
+      continue;
+    }
+    const label = menuSafe(e.label);
+    if (e.items.length > 0) {
+      rows.push("S\x1f" + label);
+      flattenMenu(e.items, rows);
+      rows.push("E");
+      continue;
+    }
+    rows.push("I\x1f" + menuSafe(e.id) + "\x1f" + label + "\x1f" + parseAccel(e.accel));
+  }
+}
+
 export class JanelaAppImpl<
   C extends CommandShapes = CommandShapes,
   E = Record<string, unknown>,
@@ -509,6 +576,44 @@ export class JanelaAppImpl<
     wvSetFullscreen(this.handle, on ? 1 : 0);
   }
 
+  /**
+   * Put submenus in the application menu.
+   *
+   * They are ADDED to the standard ones rather than replacing them, so a
+   * custom menu can never cost the app Cmd+Q or Cmd+V — replacing the bar
+   * wholesale is what would. Calling it again replaces only what a previous
+   * call added, so the menu can shrink as well as grow.
+   *
+   * Clicks arrive on `onMenu` with the entry's `id`.
+   *
+   * ```ts
+   * app.setMenu([
+   *   { label: "File", items: [
+   *     { label: "Open…", id: "open", accel: "CmdOrCtrl+O" },
+   *     { separator: true },
+   *     { label: "Close", id: "close" },
+   *   ]},
+   * ]);
+   * app.onMenu((id) => { if (id === "open") … });
+   * ```
+   *
+   * Returns false where custom menus are not supported yet — everything but
+   * macOS. The standard menu is unaffected either way.
+   */
+  setMenu(entries: MenuEntry[]): boolean {
+    const rows: string[] = [];
+    flattenMenu(entries, rows);
+    return wvSetMenu(this.handle, rows.join("\n")) === 0;
+  }
+
+  /** Called with the `id` of the clicked menu entry. */
+  onMenu(cb: (id: string) => void): void {
+    wvOnMenu(this.handle, (id) => {
+      cb(id);
+      return 0;
+    });
+  }
+
   /**
    * Fire an event into the page; the payload is delivered as a value. Under a
    * contract, the name must be declared and the payload must match its type.

package/runtime/types.ts

@@ -41,6 +41,55 @@ export type AsyncCommandHandler = (
  */
 export type FsCallback = (err: string | null, text: string) => void;
 
+/**
+ * One entry in the application menu.
+ *
+ * Every field is required rather than optional, and the entries are built with
+ * `submenu`, `menuItem` and `menuSeparator` rather than written as literals.
+ * That is a scriptc constraint made into a nicer API: a record whose fields are
+ * all optional infers as `{ label: string | undefined, … }`, and an array
+ * mixing a submenu, an item and a separator is a union that will not re-tag
+ * into it ("union types must match exactly", SC2003). The helpers each return
+ * the same total shape, so the array is homogeneous and the call site reads as
+ * a tree.
+ *
+ * ```ts
+ * app.setMenu([
+ *   submenu("File", [
+ *     menuItem("Open…", "open", "CmdOrCtrl+O"),
+ *     menuSeparator(),
+ *   ]),
+ * ]);
+ * ```
+ */
+export type MenuEntry = {
+  label: string;
+  /** Sent to `onMenu` when clicked. Empty for submenus and separators. */
+  id: string;
+  /**
+   * A shortcut like "CmdOrCtrl+O" or "CmdOrCtrl+Shift+S". Modifiers: Cmd,
+   * Ctrl, CmdOrCtrl, Alt/Option, Shift. Empty for none.
+   */
+  accel: string;
+  separator: boolean;
+  /** Children. Empty for a leaf. */
+  items: MenuEntry[];
+};
+
+/** A clickable entry. `accel` is "" for no shortcut. */
+export function menuItem(label: string, id: string, accel: string): MenuEntry {
+  return { label: label, id: id, accel: accel, separator: false, items: [] };
+}
+
+/** A divider. */
+export function menuSeparator(): MenuEntry {
+  return { label: "", id: "", accel: "", separator: true, items: [] };
+}
+
+/** A submenu holding other entries. Nestable. */
+export function submenu(label: string, items: MenuEntry[]): MenuEntry {
+  return { label: label, id: "", accel: "", separator: false, items: items };
+}
 /** A named group of extensions offered in a dialog's file-type popup. */
 export interface DialogFilter {
   name: string;

package/shim/wvshim.cc

@@ -75,6 +75,15 @@ struct App {
   void *on_invoke_ctx = nullptr;
   void (*on_timer)(int32_t, void *) = nullptr;
   void *on_timer_ctx = nullptr;
+  int32_t (*on_menu)(const uint8_t *, size_t, void *) = nullptr;
+  void *on_menu_ctx = nullptr;
+
+  // Custom menu item ids, indexed by the NSMenuItem's tag. The menu bar is
+  // process-global on macOS, so only one app can own it — see g_menu_owner.
+  std::vector<std::string> menu_ids;
+  // How many submenus the standard bar installed, so setMenu appends after
+  // them and can remove only its own on a later call.
+  size_t std_menu_count = 0;
 
   // Staging for the in-flight request.
   std::string req;      // JSON args array from JS
@@ -489,6 +498,153 @@ static void install_main_menu() {
   objc::msg_send<void>(app, objc::selector("setWindowsMenu:"), window);
 }
 
+// How many submenus the standard bar has; custom ones are appended after these
+// and only those are removed on a later setMenu.
+static size_t standard_menu_count() {
+  using namespace webview::detail;
+  objc::autoreleasepool arp;
+  id app = objc::msg_send<id>(objc::get_class("NSApplication"),
+                              objc::selector("sharedApplication"));
+  id menubar = app ? objc::msg_send<id>(app, objc::selector("mainMenu")) : nullptr;
+  if (!menubar) return 0;
+  return static_cast<size_t>(
+      objc::msg_send<NSUInteger>(menubar, objc::selector("numberOfItems")));
+}
+
+// ---- custom menus ------------------------------------------------------
+//
+// The host describes its menus declaratively in TypeScript and this renders
+// them. Nothing here parses JSON: the runtime flattens the tree into one row
+// per line, fields separated by 0x1f, which needs a split and nothing more.
+//
+//   S<US>Label      open a submenu
+//   E               close it
+//   I<US>tag<US>Label<US>key<US>mods   an item
+//   -               a separator
+//
+// A click sends the item's tag back, which indexes App::menu_ids, and the id
+// string goes up to TypeScript on the retained on_menu callback — the same
+// shape as on_invoke. The menu bar is process-global on macOS, so exactly one
+// app owns it at a time.
+static int32_t g_menu_owner = -1;
+
+static void menu_clicked(long tag) {
+  App *a = g_menu_owner >= 0 ? app_at(g_menu_owner) : nullptr;
+  if (!a || !a->on_menu) return;
+  if (tag < 0 || static_cast<size_t>(tag) >= a->menu_ids.size()) return;
+  const std::string &id = a->menu_ids[static_cast<size_t>(tag)];
+  a->on_menu(reinterpret_cast<const uint8_t *>(id.data()), id.size(),
+             a->on_menu_ctx);
+}
+
+// One shared target for every custom item; the tag says which one fired.
+static id menu_target() {
+  static id instance = nullptr;
+  if (instance) return instance;
+  constexpr auto class_name = "JanelaMenuTarget";
+  // Registering the same class twice crashes, and this runs once per process
+  // anyway — the lookup keeps a reload honest.
+  Class cls = objc_lookUpClass(class_name);
+  if (!cls) {
+    cls = objc_allocateClassPair(
+        webview::detail::objc::get_class("NSObject"), class_name, 0);
+    class_addMethod(cls, webview::detail::objc::selector("janelaMenuAction:"),
+                    (IMP)(+[](id, SEL, id sender) {
+                      menu_clicked(webview::detail::objc::msg_send<long>(
+                          sender, webview::detail::objc::selector("tag")));
+                    }),
+                    "v@:@");
+    objc_registerClassPair(cls);
+  }
+  instance = webview::detail::objc::msg_send<id>(
+      webview::detail::objc::msg_send<id>((id)cls,
+                                          webview::detail::objc::selector("alloc")),
+      webview::detail::objc::selector("init"));
+  return instance;
+}
+
+// Appends the host's submenus to the standard menu bar rather than replacing
+// it: a custom menu must not be able to cost the app Cmd+Q and Cmd+V, which is
+// what replacing the bar wholesale would do.
+static int32_t apply_custom_menu(App *a, const std::string &spec) {
+  using namespace webview::detail;
+  objc::autoreleasepool arp;
+
+  id app = objc::msg_send<id>(objc::get_class("NSApplication"),
+                              objc::selector("sharedApplication"));
+  id menubar = objc::msg_send<id>(app, objc::selector("mainMenu"));
+  if (!menubar) return -1;
+
+  // Drop whatever a previous call added, so setMenu is idempotent and can
+  // shrink the bar as well as grow it.
+  for (size_t n = objc::msg_send<NSUInteger>(menubar,
+                                             objc::selector("numberOfItems"));
+       n > a->std_menu_count; n--) {
+    objc::msg_send<void>(menubar, objc::selector("removeItemAtIndex:"),
+                         static_cast<NSInteger>(n - 1));
+  }
+  a->menu_ids.clear();
+
+  std::vector<id> stack;
+  stack.push_back(menubar);
+
+  for (const std::string &line : split_on(spec, '\n')) {
+    if (line.empty()) continue;
+    std::vector<std::string> f = split_on(line, '\x1f');
+    const std::string &kind = f[0];
+
+    if (kind == "S" && f.size() >= 2) {
+      id holder = objc::msg_send<id>(
+          objc::msg_send<id>(objc::get_class("NSMenuItem"),
+                             objc::selector("alloc")),
+          objc::selector("init"));
+      id menu = objc::msg_send<id>(
+          objc::msg_send<id>(objc::get_class("NSMenu"),
+                             objc::selector("alloc")),
+          objc::selector("initWithTitle:"),
+          cocoa::NSString_stringWithUTF8String(f[1]));
+      objc::msg_send<void>(holder, objc::selector("setTitle:"),
+                           cocoa::NSString_stringWithUTF8String(f[1]));
+      objc::msg_send<void>(holder, objc::selector("setSubmenu:"), menu);
+      objc::msg_send<void>(stack.back(), objc::selector("addItem:"), holder);
+      stack.push_back(menu);
+    } else if (kind == "E") {
+      if (stack.size() > 1) stack.pop_back();
+    } else if (kind == "-") {
+      if (stack.size() > 1) {
+        objc::msg_send<void>(
+            stack.back(), objc::selector("addItem:"),
+            objc::msg_send<id>(objc::get_class("NSMenuItem"),
+                               objc::selector("separatorItem")));
+      }
+    } else if (kind == "I" && f.size() >= 5 && stack.size() > 1) {
+      a->menu_ids.push_back(f[1]);
+      long tag = static_cast<long>(a->menu_ids.size()) - 1;
+      id it = objc::msg_send<id>(
+          objc::msg_send<id>(objc::get_class("NSMenuItem"),
+                             objc::selector("alloc")),
+          objc::selector("initWithTitle:action:keyEquivalent:"),
+          cocoa::NSString_stringWithUTF8String(f[2]),
+          objc::selector("janelaMenuAction:"),
+          cocoa::NSString_stringWithUTF8String(f[3]));
+      objc::msg_send<void>(it, objc::selector("setTarget:"), menu_target());
+      objc::msg_send<void>(it, objc::selector("setTag:"), tag);
+      // Always set the mask, including 0: AppKit's default for a key
+      // equivalent is Command, so leaving it alone would turn an accelerator
+      // with no modifiers into a Command shortcut.
+      NSUInteger mods = static_cast<NSUInteger>(strtoul(f[4].c_str(), nullptr, 10));
+      objc::msg_send<void>(it, objc::selector("setKeyEquivalentModifierMask:"),
+                           mods);
+      objc::msg_send<void>(stack.back(), objc::selector("addItem:"), it);
+    }
+  }
+  g_menu_owner = -1;
+  for (int32_t i = 0; i < 8; i++) {
+    if (app_at(i) == a) { g_menu_owner = i; break; }
+  }
+  return 0;
+}
+
 bool run_file_dialog(const DialogRequest &req, std::vector<std::string> &out,
                      std::string &error) {
   (void)error;
@@ -745,6 +901,14 @@ bool run_file_dialog(const DialogRequest &req, std::vector<std::string> &out,
 // the editing keys are handled inside WebView2 and WebKitGTK. A menu here
 // would be a feature, not a fix.
 static void install_main_menu() {}
+static size_t standard_menu_count() { return 0; }
+
+// Custom menus are macOS-only for now. Two things have to be solved first:
+// webview.h's win32 loop never calls TranslateAcceleratorW, without which
+// accelerators do not fire, and the GTK backend keeps both GTK 3 and GTK 4
+// alive where GTK 4 removed GtkMenuBar. Reporting -1 lets the host say
+// "unsupported here" rather than pretend it worked.
+static int32_t apply_custom_menu(App *, const std::string &) { return -1; }
 #endif
 
 // Runs on the UI thread with no TS frame beneath it — see the note on the job
@@ -868,8 +1032,9 @@ int32_t wv_create(int32_t debug) {
     webview_t w = webview_create(debug, nullptr);
     if (!w) return -1;
     // After webview_create, which is what brings NSApplication into being.
-    // A no-op off macOS.
+    // Both are no-ops off macOS.
     install_main_menu();
+    g_apps[i].std_menu_count = standard_menu_count();
     // Field-wise reset: App holds a thread and atomics, so it is not
     // copy-assignable from a temporary.
     g_apps[i].binds.clear();
@@ -877,6 +1042,9 @@ int32_t wv_create(int32_t debug) {
     g_apps[i].on_invoke_ctx = nullptr;
     g_apps[i].on_timer = nullptr;
     g_apps[i].on_timer_ctx = nullptr;
+    g_apps[i].on_menu = nullptr;
+    g_apps[i].on_menu_ctx = nullptr;
+    g_apps[i].menu_ids.clear();
     g_apps[i].req.clear();
     g_apps[i].cur_id.clear();
     g_apps[i].reply.clear();
@@ -1179,6 +1347,27 @@ int32_t wv_dialog(int32_t h, int32_t kind, int32_t flags, const uint8_t *tp,
 
 // ---- window control ---------------------------------------------------------
 
+// Renders the host's declarative menu. The spec is one row per line with 0x1f
+// between fields; the runtime flattens the tree, so nothing here parses JSON.
+// Returns -1 where custom menus are not supported yet (everything but macOS),
+// which the host reports rather than swallowing.
+int32_t wv_set_menu(int32_t h, const uint8_t *p, size_t n) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  return apply_custom_menu(a, to_str(p, n));
+}
+
+// Retained, like wv_on_invoke: registered once and valid until the app exits.
+int32_t wv_on_menu(int32_t h,
+                   int32_t (*cb)(const uint8_t *, size_t, void *),
+                   void *ctx) {
+  App *a = app_at(h);
+  if (!a) return -1;
+  a->on_menu = cb;
+  a->on_menu_ctx = ctx;
+  return 0;
+}
+
 int32_t wv_set_fullscreen(int32_t h, int32_t on) {
   App *a = app_at(h);
   if (!a) return -1;