janela 0.16.0 → 0.17.0

package/bin/lib.mjs

@@ -223,6 +223,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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "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
@@ -358,6 +367,284 @@ bool run_file_dialog(const DialogRequest &req, std::vector<std::string> &out,
 
 #if defined(__APPLE__)
 
+// A standard macOS main menu.
+//
+// On macOS a Command-key shortcut is a MENU key equivalent, not a
+// window-manager gesture the way Alt+F4 is on Windows. With no main menu
+// nothing claims Cmd+Q, Cmd+C, Cmd+V, Cmd+Z or Cmd+A, and a webview app simply
+// appears to ignore them — the window had zero menu bars, which is exactly
+// what that looks like from the outside.
+//
+// webview.h leaves this to the embedder on purpose: webview/webview#127 is
+// still open, and #237, which added precisely this Edit menu, was closed with
+// "anyone who is impatient can always take this code on their own". Tauri does
+// the same thing one layer up, through muda.
+//
+// Every item here is a STANDARD AppKit selector travelling up the responder
+// chain, so there is nothing to call back into TypeScript for and no new FFI
+// surface. WKWebView answers the editing ones itself. Custom menus — a
+// declarative table passed down from the host — are a separate feature.
+static void install_main_menu() {
+  using namespace webview::detail;
+  objc::autoreleasepool arp;
+
+  id app = objc::msg_send<id>(objc::get_class("NSApplication"),
+                              objc::selector("sharedApplication"));
+  if (!app) return;
+  // Idempotent: an embedder that already installed a menu keeps it.
+  if (objc::msg_send<id>(app, objc::selector("mainMenu"))) return;
+
+  // NSEventModifierFlags. The default for a key equivalent is Command alone,
+  // so only the combinations need naming.
+  const NSUInteger kShift = 1UL << 17;
+  const NSUInteger kControl = 1UL << 18;
+  const NSUInteger kOption = 1UL << 19;
+  const NSUInteger kCommand = 1UL << 20;
+
+  auto str = [](const std::string &v) {
+    return cocoa::NSString_stringWithUTF8String(v);
+  };
+  auto alloc_init = [](const char *cls) {
+    return objc::msg_send<id>(
+        objc::msg_send<id>(objc::get_class(cls), objc::selector("alloc")),
+        objc::selector("init"));
+  };
+
+  // AppKit labels the first submenu from the bundle, not from this title, but
+  // "About <name>" and "Quit <name>" are ours to spell.
+  id process = objc::msg_send<id>(objc::get_class("NSProcessInfo"),
+                                  objc::selector("processInfo"));
+  const char *raw =
+      process ? objc::msg_send<const char *>(
+                    objc::msg_send<id>(process, objc::selector("processName")),
+                    objc::selector("UTF8String"))
+              : nullptr;
+  std::string name = raw ? raw : "App";
+
+  id menubar = alloc_init("NSMenu");
+
+  auto submenu = [&](const std::string &title) {
+    id holder = alloc_init("NSMenuItem");
+    id menu = objc::msg_send<id>(
+        objc::msg_send<id>(objc::get_class("NSMenu"), objc::selector("alloc")),
+        objc::selector("initWithTitle:"), str(title));
+    objc::msg_send<void>(holder, objc::selector("setSubmenu:"), menu);
+    objc::msg_send<void>(menubar, objc::selector("addItem:"), holder);
+    return menu;
+  };
+
+  auto item = [&](id menu, const std::string &title, const char *sel,
+                  const std::string &key, NSUInteger mods) {
+    id it = objc::msg_send<id>(
+        objc::msg_send<id>(objc::get_class("NSMenuItem"),
+                           objc::selector("alloc")),
+        objc::selector("initWithTitle:action:keyEquivalent:"), str(title),
+        sel ? objc::selector(sel) : nullptr, str(key));
+    if (mods) {
+      objc::msg_send<void>(
+          it, objc::selector("setKeyEquivalentModifierMask:"), mods);
+    }
+    objc::msg_send<void>(menu, objc::selector("addItem:"), it);
+  };
+  auto separator = [&](id menu) {
+    objc::msg_send<void>(menu, objc::selector("addItem:"),
+                         objc::msg_send<id>(objc::get_class("NSMenuItem"),
+                                            objc::selector("separatorItem")));
+  };
+
+  id app_menu = submenu(name);
+  item(app_menu, "About " + name, "orderFrontStandardAboutPanel:", "", 0);
+  separator(app_menu);
+  item(app_menu, "Hide " + name, "hide:", "h", 0);
+  item(app_menu, "Hide Others", "hideOtherApplications:", "h",
+       kOption | kCommand);
+  item(app_menu, "Show All", "unhideAllApplications:", "", 0);
+  separator(app_menu);
+  // performClose:, not terminate: — measured, not assumed. Both quit and
+  // both exit 0, but terminate: exits the process itself, so the host never
+  // returns from wv_run and anything after app.run() is skipped;
+  // performClose: goes through the same window-close path the red button
+  // uses, the run loop unwinds, and the host prints its own "run returned 0".
+  // One shutdown path instead of two. muda picks terminate: because Tauri's
+  // app logic is native and multi-window; janela is single-window, so closing
+  // the window IS quitting. If janela ever grows multiple windows this has to
+  // become a real Quit that closes all of them.
+  //
+  // (An earlier note here claimed performClose: did not fire at all. That was
+  // a bad test: posted key events go to the FRONTMOST app, and the app was not
+  // active. With it activated first, both actions work.)
+  item(app_menu, "Quit " + name, "performClose:", "q", 0);
+
+  id edit = submenu("Edit");
+  item(edit, "Undo", "undo:", "z", 0);
+  item(edit, "Redo", "redo:", "z", kShift | kCommand);
+  separator(edit);
+  item(edit, "Cut", "cut:", "x", 0);
+  item(edit, "Copy", "copy:", "c", 0);
+  item(edit, "Paste", "paste:", "v", 0);
+  item(edit, "Select All", "selectAll:", "a", 0);
+
+  id view = submenu("View");
+  item(view, "Enter Full Screen", "toggleFullScreen:", "f",
+       kControl | kCommand);
+
+  id window = submenu("Window");
+  item(window, "Minimize", "performMiniaturize:", "m", 0);
+  item(window, "Close", "performClose:", "w", 0);
+
+  objc::msg_send<void>(app, objc::selector("setMainMenu:"), menubar);
+  // Lets AppKit add the standard Window-menu bookkeeping (window list,
+  // Bring All to Front).
+  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;
@@ -608,6 +895,22 @@ bool run_file_dialog(const DialogRequest &req, std::vector<std::string> &out,
 
 #endif
 
+#if !defined(__APPLE__)
+// Windows and Linux need no menu for these shortcuts: Alt+F4 is a
+// window-manager message the win32 backend already answers as WM_CLOSE, and
+// 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
 // pool above for why that matters.
 void dialog_on_ui_thread(webview_t, void *arg) {
@@ -728,6 +1031,10 @@ int32_t wv_create(int32_t debug) {
     if (g_apps[i].used) continue;
     webview_t w = webview_create(debug, nullptr);
     if (!w) return -1;
+    // After webview_create, which is what brings NSApplication into being.
+    // 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();
@@ -735,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();
@@ -1037,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;