basalt-core 0.0.0-rc5

package/native/core/KeyEvents.h

@@ -0,0 +1,144 @@
+// Which view claims which key, and what a key is called.
+//
+// `onKeyPress` on a `<TextInput>` existed and a `<View>` had nothing, so an app
+// could not bind a shortcut to anything it draws. On a phone that is no loss; on
+// a desktop it is most of the interface.
+//
+// ## The vocabulary is a browser's
+//
+// A key is named the way `KeyboardEvent.key` names it: `"a"`, `"A"`, `" "`,
+// `"ArrowLeft"`, `"Escape"`, `"F5"`. react-native-macos and react-native-windows
+// both use these, so an app that binds `"ArrowLeft"` means the same thing on all
+// five platforms it might run on. The names live here as constants rather than as
+// string literals in three hosts, for the reason core/TestQuitFile.h gives about
+// shared spellings: three places to write "ArrowLeft" is three places to write
+// "ArrowLeft " instead, and the failure is a shortcut that silently never fires.
+//
+// Case follows the character, as it does in a browser: Shift+A is `"A"` and its
+// `shift` modifier is also set. An app may bind either and both are honest.
+//
+// ## Why a view declares its keys in advance
+//
+// Because a host has to decide whether a key was handled *before* it can do
+// anything else, and it cannot ask JavaScript at that moment. An unhandled key
+// must still reach the application menu, a focused text field, or a scroll view
+// that scrolls on arrows; a handled one must not. That decision is the return
+// value of `performKeyEquivalent:`, of GTK's `key-pressed` handler, and of
+// whether `WM_KEYDOWN` reaches `DefWindowProc` -- three synchronous answers, and
+// a round trip through the JavaScript thread is not available to any of them.
+//
+// So `handledBy` is the whole point of this file: a host asks it, gets an answer
+// in the same call stack, and consumes the key or passes it on accordingly.
+// Reporting the press to JavaScript happens afterwards and asynchronously,
+// because by then the decision has been made.
+//
+// ## Why the registry is here
+//
+// Three hosts asking "does this view claim Cmd+Z" is one decision, and a host
+// keeping its own copy would be a fourth place for it to drift. The tags are
+// React's, so nothing here knows what a view is.
+
+#pragma once
+
+#include <react/renderer/core/ReactPrimitives.h>
+
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+// The names that are not a character. A host maps its own key codes onto these;
+// what it must not do is spell them itself.
+inline constexpr const char *kKeyArrowUp = "ArrowUp";
+inline constexpr const char *kKeyArrowDown = "ArrowDown";
+inline constexpr const char *kKeyArrowLeft = "ArrowLeft";
+inline constexpr const char *kKeyArrowRight = "ArrowRight";
+inline constexpr const char *kKeyEnter = "Enter";
+inline constexpr const char *kKeyTab = "Tab";
+inline constexpr const char *kKeyEscape = "Escape";
+inline constexpr const char *kKeyBackspace = "Backspace";
+inline constexpr const char *kKeyDelete = "Delete";
+inline constexpr const char *kKeyHome = "Home";
+inline constexpr const char *kKeyEnd = "End";
+inline constexpr const char *kKeyPageUp = "PageUp";
+inline constexpr const char *kKeyPageDown = "PageDown";
+// A space is a character like any other, and is named `" "` rather than
+// `"Space"`. Worth a constant because it is the one that looks like a mistake.
+inline constexpr const char *kKeySpace = " ";
+
+struct KeyModifiers {
+  bool alt = false;
+  bool ctrl = false;
+  bool meta = false;
+  bool shift = false;
+
+  bool operator==(const KeyModifiers &other) const {
+    return alt == other.alt && ctrl == other.ctrl && meta == other.meta &&
+           shift == other.shift;
+  }
+  bool operator!=(const KeyModifiers &other) const { return !(*this == other); }
+};
+
+// A press, and also a claim: the two are compared for equality, so they are one
+// shape rather than two that have to agree.
+struct KeyCombination {
+  std::string key;
+  KeyModifiers modifiers;
+
+  bool operator==(const KeyCombination &other) const {
+    return key == other.key && modifiers == other.modifiers;
+  }
+};
+
+// What a view claims. Replaces whatever it claimed before rather than adding to
+// it: a re-render produces the whole list, and merging would leave a shortcut
+// live after the app stopped declaring it.
+void setHandledKeys(facebook::react::Tag tag, std::vector<KeyCombination> combinations);
+
+// On unmount. Not on every mutation -- an empty list is a view that claims
+// nothing and still exists.
+void clearHandledKeys(facebook::react::Tag tag);
+
+// Whether that one view claims it.
+bool handlesKey(facebook::react::Tag tag, const KeyCombination &pressed);
+
+// The nearest view in `path` that claims it, or nothing. `path` runs from the
+// focused view outwards to the root, so the first match is the innermost -- the
+// same walk `DragAndDrop`'s drop targets use, and the same reason: a shortcut on
+// a pane should win over the same shortcut on the window.
+std::optional<facebook::react::Tag> handledBy(
+    const std::vector<facebook::react::Tag> &path, const KeyCombination &pressed);
+
+// Any view that claims it, focus ignored. For the case where nothing has focus
+// at all, which is the ordinary state of a window whose app has declared
+// window-level shortcuts and focused nothing.
+//
+// **Only when nothing is focused.** A host with a focused view must use
+// `handledBy`, because a claim outside the focus path is exactly how a background
+// pane would steal a keystroke from a text field. With nothing focused there is no
+// text field taking keys and no path to be outside of, so the choice is between a
+// window-level shortcut working and it never firing -- and never firing is what a
+// `<KeyHandler>` below the root got before this existed, which is every app that
+// declares shortcuts once at the top.
+//
+// Ambiguous by construction when two views claim the same combination and neither
+// is focused. The first found answers, and which that is depends on the registry's
+// order -- so an app with two window-level handlers for one combination gets one
+// of them and no promise which. Worth knowing rather than worth preventing: the
+// alternative is refusing to fire at all.
+std::optional<facebook::react::Tag> handledByAny(const KeyCombination &pressed);
+
+// How many views currently claim anything. For tests, and for a host that wants
+// to skip the walk entirely when nothing is listening.
+std::size_t handledKeyViewCount();
+
+// Reporting, after the host has already decided. Set by whatever carries events
+// to JavaScript; absent until then, in which case a press is dropped rather than
+// queued -- a shortcut that fires late is worse than one that did not fire.
+void setKeyListener(std::function<void(facebook::react::Tag, const KeyCombination &)> listener);
+void reportKey(facebook::react::Tag tag, const KeyCombination &pressed);
+
+} // namespace basalt

package/native/core/LogBoxSurface.cpp

@@ -0,0 +1,46 @@
+#include "LogBoxSurface.h"
+
+#include "PlatformServices.h"
+
+namespace basalt {
+
+LogBoxSurfaceDelegate::LogBoxSurfaceDelegate(Show show, Hide hide)
+    : show_(std::move(show)), hide_(std::move(hide)) {}
+
+void LogBoxSurfaceDelegate::createContentView(std::string appKey) {
+  // Only recorded. The module constructs on the JavaScript thread and calls
+  // this at once, long before anything wants a surface on screen, and starting
+  // one here would mean touching widgets from the wrong thread for no gain.
+  appKey_ = std::move(appKey);
+}
+
+bool LogBoxSurfaceDelegate::isContentViewReady() {
+  return !appKey_.empty();
+}
+
+void LogBoxSurfaceDelegate::destroyContentView() {
+  hide();
+  appKey_.clear();
+}
+
+void LogBoxSurfaceDelegate::show() {
+  if (showing_ || appKey_.empty() || !show_) {
+    return;
+  }
+  showing_ = true;
+  postToUiThread([show = show_, appKey = appKey_]() { show(appKey); });
+}
+
+void LogBoxSurfaceDelegate::hide() {
+  if (!showing_ || !hide_) {
+    return;
+  }
+  showing_ = false;
+  postToUiThread([hide = hide_]() { hide(); });
+}
+
+bool LogBoxSurfaceDelegate::isShowing() {
+  return showing_;
+}
+
+} // namespace basalt

package/native/core/LogBoxSurface.h

@@ -0,0 +1,68 @@
+// React Native's error inspector, which is a second surface.
+//
+// The red box is not a native window that a host draws. It is React Native's
+// own JavaScript -- `LogBoxInspectorContainer` -- registered by AppRegistry
+// under the name `"LogBox"`, exactly as an app registers its own component. So
+// a host does not implement an error overlay; it starts a second surface for a
+// component it did not write, on top of the first.
+//
+// That is easy to miss, and missing it is why the inspector did not appear on
+// this platform while the *toasts* did: the notification strip is rendered
+// inside the app's own surface by `AppContainer`, so it has worked since
+// `<View>` and `<Text>` did. Only the full-screen inspector needs a second
+// surface, and the only thing that asks for one is the `LogBox` TurboModule --
+// which ReactCxxPlatform already implements, and only provides when a host
+// hands `ReactHost` a `SurfaceDelegate`. Passing null, as this project did,
+// leaves `NativeLogBox.show()` a call into nothing.
+//
+// ## What is portable about a surface delegate
+//
+// Everything except making a root and starting a surface. The interface has six
+// methods and four of them are bookkeeping; the two that are not are called
+// from the JavaScript thread and have to reach the thread that owns widgets.
+// Getting that wrong is a mounting-manager assertion on a good day. So the
+// bookkeeping and the thread hop are here, once, and a host supplies two
+// functions.
+
+#pragma once
+
+#include <react/renderer/scheduler/SurfaceDelegate.h>
+
+#include <functional>
+#include <string>
+
+namespace basalt {
+
+class LogBoxSurfaceDelegate final : public facebook::react::SurfaceDelegate {
+ public:
+  // `show` is handed the app key React Native registered the inspector under,
+  // which is always "LogBox" but is passed rather than assumed -- it is the
+  // module that decides, and a host should not have to know the string.
+  using Show = std::function<void(const std::string &appKey)>;
+  using Hide = std::function<void()>;
+
+  LogBoxSurfaceDelegate(Show show, Hide hide);
+
+  // --- SurfaceDelegate ------------------------------------------------------
+  //
+  // Called from the JavaScript thread: `createContentView` from the module's
+  // constructor, `show` and `hide` from LogBoxData's setTimeout. So the two
+  // that touch a surface hop to the UI thread and the rest only record.
+  void createContentView(std::string appKey) override;
+  bool isContentViewReady() override;
+  void destroyContentView() override;
+  void show() override;
+  void hide() override;
+  bool isShowing() override;
+
+ private:
+  Show show_;
+  Hide hide_;
+  std::string appKey_;
+  // Written on the JavaScript thread and read there too -- every caller of this
+  // interface is that thread -- so this needs no lock. The UI thread sees only
+  // the two callbacks, and never this.
+  bool showing_{false};
+};
+
+} // namespace basalt

package/native/core/MenuModel.h

@@ -0,0 +1,117 @@
+// An application menu, described once.
+//
+// The menu bar is the one desktop feature where the three platforms disagree
+// about whether it should exist at all, and this file is shaped by that rather
+// than pretending otherwise.
+//
+//   macOS    Every application has one, it lives in the system menu bar, and it
+//            is not optional -- it is also load-bearing. AppKit routes a key
+//            equivalent through the main menu before anything else sees it, so
+//            an app with no Edit menu has no working Cmd-C: the field editor
+//            never receives `copy:`. That was true of this host until this file
+//            existed, and it is the reason it exists now.
+//
+//   Windows  Conventional for some applications and absent from many. It is a
+//            bar inside the window, so it costs client area.
+//
+//   GNOME    Discouraged outright: the HIG has said to use a header bar and a
+//            menu button since GNOME 3, and GTK4 removed the widget that made
+//            the old arrangement easy.
+//
+// So an app describes a menu here, and each platform decides what to do with
+// the description. What it must never do is quietly nothing, which is why
+// `applicationMenuSupported()` exists: an app can ask, and this project's own
+// documentation can say, rather than an app shipping with a File menu nobody
+// on Linux can see.
+//
+// ## Roles
+//
+// An item with a `role` is one the platform implements itself -- copy, paste,
+// quit, minimise. It never reaches JavaScript, which is not an optimisation: on
+// macOS `copy:` has to travel the responder chain to reach whichever field has
+// focus, and a round trip through a callback would arrive with the chain gone.
+// The role names are Electron's, because that is the vocabulary a desktop
+// developer already has.
+
+#pragma once
+
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+struct MenuItemModel {
+  // What it says. Ignored for a separator, and optional for a role, where the
+  // platform's own word for it is better than any this project would choose.
+  std::string label;
+
+  // One of the names in kMenuRoles below, or empty for an item the app
+  // implements. An unknown role is dropped rather than shown: a menu item that
+  // does nothing is worse than one that is not there.
+  std::string role;
+
+  // "CmdOrCtrl+O", in Electron's spelling. Ignored for a role, which brings the
+  // platform's own shortcut with it.
+  std::string accelerator;
+
+  bool enabled{true};
+  bool separator{false};
+
+  // What comes back when the app's own item is chosen. Zero for a role or a
+  // separator, and for a submenu's parent.
+  int id{0};
+
+  std::vector<MenuItemModel> submenu;
+};
+
+// The top level of a menu bar: each entry is a menu, and its `submenu` is what
+// drops down. An entry with no submenu is dropped -- no desktop has a bare
+// command in a menu bar.
+using MenuModel = std::vector<MenuItemModel>;
+
+// The roles a platform is expected to implement itself, in Electron's spelling.
+// Anything else in `role` is unknown and the item is dropped.
+//
+// Deliberately short. Each one is a thing every desktop already has a standard
+// action and shortcut for; a role that only one platform has would be a role
+// apps cannot use.
+inline constexpr const char *kMenuRoles[] = {
+    "about", "quit",   "undo",  "redo",   "cut",     "copy",
+    "paste", "delete", "selectAll", "minimize", "zoom", "close",
+    "togglefullscreen",
+};
+
+// Whether this platform puts an application menu anywhere a person can see it.
+//
+// False is not a failure and not a promise to fix: see the header. An app that
+// asks can put its commands somewhere else; one that does not is no worse off
+// than it was.
+bool applicationMenuSupported();
+
+// Installs `menu` as the application menu, replacing whatever was there.
+//
+// `onChosen` is called with the `id` of an app's own item, on the UI thread. A
+// role never arrives there. An empty menu restores the platform's default,
+// which on macOS is the minimum an application needs to be closable.
+void setApplicationMenu(const MenuModel &menu, std::function<void(int id)> onChosen);
+
+// The menu that is actually installed, as text, for BASALT_DUMP_MENU.
+//
+// Read back from the platform rather than remembered from the model, which is
+// the whole point: it says the description became a real NSMenu or HMENU, with
+// the shortcuts the platform attached to its roles. Empty on a platform with no
+// menu bar.
+//
+// One line per item, two spaces of indent per level:
+//
+//     Edit
+//       Copy [cmd+c]
+//       Paste [cmd+v]
+//       -
+//       Nothing doing (disabled)
+//
+// Called on the UI thread.
+std::string describeApplicationMenu();
+
+} // namespace basalt

package/native/core/MenuModule.cpp

@@ -0,0 +1,209 @@
+#include "MenuModule.h"
+
+#include "MenuModel.h"
+#include "PlatformServices.h"
+#include "TestDialog.h"
+
+#include <react/bridging/Bridging.h>
+#include <react/bridging/Promise.h>
+
+#include <folly/dynamic.h>
+
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace basalt {
+
+namespace {
+
+using facebook::jsi::Array;
+using facebook::jsi::Object;
+using facebook::jsi::Runtime;
+using facebook::jsi::Value;
+using facebook::react::TurboModule;
+
+std::string stringProperty(Runtime &runtime, const Object &item, const char *name) {
+  const Value value = item.getProperty(runtime, name);
+  return value.isString() ? value.asString(runtime).utf8(runtime) : std::string{};
+}
+
+bool boolProperty(Runtime &runtime, const Object &item, const char *name, bool fallback) {
+  const Value value = item.getProperty(runtime, name);
+  return value.isBool() ? value.asBool() : fallback;
+}
+
+// A context menu's entries, which are a flatter thing than the application
+// menu's: one level, no roles, no submenus. That is not a simplification -- a
+// popup menu on all three desktops is a list, and the nesting an application
+// menu has is what a menu *bar* is for.
+std::vector<MenuEntry> entriesFrom(Runtime &runtime, const Value &value) {
+  std::vector<MenuEntry> entries;
+  if (!value.isObject() || !value.asObject(runtime).isArray(runtime)) {
+    return entries;
+  }
+  const Array array = value.asObject(runtime).asArray(runtime);
+  const size_t length = array.size(runtime);
+  for (size_t i = 0; i < length; i++) {
+    const Value element = array.getValueAtIndex(runtime, i);
+    if (!element.isObject()) {
+      continue;
+    }
+    const Object item = element.asObject(runtime);
+    // `{separator: true}`, which reads better in JavaScript than the empty
+    // label the platforms use. An item with no label is one too, so an app that
+    // built its list by filtering does not have to notice.
+    if (boolProperty(runtime, item, "separator", false)) {
+      entries.push_back(MenuEntry::separator());
+      continue;
+    }
+    MenuEntry entry;
+    entry.label = stringProperty(runtime, item, "label");
+    entry.enabled = boolProperty(runtime, item, "enabled", true);
+    entry.shortcut = stringProperty(runtime, item, "shortcut");
+    entries.push_back(std::move(entry));
+  }
+  return entries;
+}
+
+std::vector<MenuItemModel> itemsFrom(Runtime &runtime, const Array &array);
+
+MenuItemModel itemFrom(Runtime &runtime, const Object &item) {
+  MenuItemModel model;
+  model.label = stringProperty(runtime, item, "label");
+  model.role = stringProperty(runtime, item, "role");
+  model.accelerator = stringProperty(runtime, item, "accelerator");
+
+  const Value separator = item.getProperty(runtime, "separator");
+  model.separator = separator.isBool() && separator.asBool();
+
+  const Value enabled = item.getProperty(runtime, "enabled");
+  // Absent means enabled: an app listing an item without saying meant to show
+  // it, and defaulting the other way would grey out every menu ever written.
+  model.enabled = !enabled.isBool() || enabled.asBool();
+
+  const Value id = item.getProperty(runtime, "id");
+  model.id = id.isNumber() ? static_cast<int>(id.asNumber()) : 0;
+
+  const Value submenu = item.getProperty(runtime, "submenu");
+  if (submenu.isObject() && submenu.asObject(runtime).isArray(runtime)) {
+    model.submenu = itemsFrom(runtime, submenu.asObject(runtime).asArray(runtime));
+  }
+  return model;
+}
+
+std::vector<MenuItemModel> itemsFrom(Runtime &runtime, const Array &array) {
+  std::vector<MenuItemModel> items;
+  const size_t length = array.size(runtime);
+  items.reserve(length);
+  for (size_t i = 0; i < length; i++) {
+    const Value entry = array.getValueAtIndex(runtime, i);
+    if (entry.isObject()) {
+      items.push_back(itemFrom(runtime, entry.asObject(runtime)));
+    }
+  }
+  return items;
+}
+
+} // namespace
+
+DesktopMenuModule::DesktopMenuModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+    : TurboModule(kModuleName, std::move(jsInvoker)) {
+  methodMap_["setApplicationMenu"] = MethodMetadata{1, setMenu};
+  methodMap_["isSupported"] = MethodMetadata{0, isSupported};
+  methodMap_["showContextMenu"] = MethodMetadata{3, showContextMenu};
+  // What a NativeEventEmitter over this module calls; the events go out as
+  // device events either way.
+  methodMap_["addListener"] = MethodMetadata{1, noop};
+  methodMap_["removeListeners"] = MethodMetadata{1, noop};
+}
+
+DesktopMenuModule::~DesktopMenuModule() {
+  // The handler holds a pointer to this module's emitter. Cleared on the way
+  // out, for the same reason the title bar clears its metrics listener.
+  setApplicationMenu(MenuModel{}, nullptr);
+}
+
+Value DesktopMenuModule::setMenu(Runtime &runtime,
+                                 TurboModule &module,
+                                 const Value *args,
+                                 size_t count) {
+  MenuModel model;
+  if (count >= 1 && args[0].isObject() && args[0].asObject(runtime).isArray(runtime)) {
+    model = itemsFrom(runtime, args[0].asObject(runtime).asArray(runtime));
+  }
+
+  auto *self = static_cast<DesktopMenuModule *>(&module);
+  // Installed on the UI thread, like everything else that touches a window:
+  // this arrives on the JavaScript thread and an NSMenu or an HMENU may not be
+  // built there.
+  postToUiThread([self, model = std::move(model)] {
+    setApplicationMenu(model, [self](int id) {
+      self->emitDeviceEvent(kMenuChosenEvent,
+                            [id](Runtime & /*runtime*/, std::vector<Value> &args) {
+                              args.emplace_back(Value(id));
+                            });
+    });
+  });
+  return Value::undefined();
+}
+
+Value DesktopMenuModule::isSupported(Runtime & /*runtime*/,
+                                     TurboModule & /*module*/,
+                                     const Value * /*args*/,
+                                     size_t /*count*/) {
+  return Value(applicationMenuSupported());
+}
+
+Value DesktopMenuModule::noop(Runtime & /*runtime*/,
+                              TurboModule & /*module*/,
+                              const Value * /*args*/,
+                              size_t /*count*/) {
+  return Value::undefined();
+}
+
+Value DesktopMenuModule::showContextMenu(Runtime &runtime,
+                                         TurboModule &module,
+                                         const Value *args,
+                                         size_t count) {
+  MenuRequest request;
+  if (count >= 1) {
+    request.entries = entriesFrom(runtime, args[0]);
+  }
+  // Negative is "wherever the pointer is", which is what the seam already means
+  // and what a menu opened from the keyboard wants. An app that passes nothing
+  // gets that rather than the top-left corner.
+  if (count >= 3 && args[1].isNumber() && args[2].isNumber()) {
+    request.x = args[1].asNumber();
+    request.y = args[2].asNumber();
+  }
+
+  auto jsInvoker = static_cast<DesktopMenuModule &>(module).jsInvoker_;
+  auto promise =
+      std::make_shared<facebook::react::AsyncPromise<folly::dynamic>>(runtime, jsInvoker);
+
+  if (request.entries.empty()) {
+    // Nothing to show. Resolved rather than rejected: an app whose menu came
+    // out empty because everything was filtered away has not made a mistake,
+    // and a rejection would make it handle one.
+    promise->resolve(folly::dynamic(nullptr));
+    return Value(runtime, facebook::react::bridging::toJs(runtime, *promise, jsInvoker));
+  }
+
+  // `presentMenu`, not `showMenu`: everything that would put a popup on screen
+  // goes through the scripted answer, and here it is not merely tidiness. On
+  // macOS `popUpMenuPositioningItem` runs the menu's own tracking loop on the
+  // main thread, so a menu nobody dismisses stops an automated run where it
+  // stands. See core/TestDialog.h.
+  presentMenu(request, [promise](int index) {
+    // Null for dismissed, which is the same shape the file dialogs answer a
+    // cancel with: an index is a number, and a caller checking `if (index)`
+    // would read entry zero as nothing.
+    promise->resolve(index < 0 ? folly::dynamic(nullptr) : folly::dynamic(index));
+  });
+
+  return Value(runtime, facebook::react::bridging::toJs(runtime, *promise, jsInvoker));
+}
+
+} // namespace basalt

package/native/core/MenuModule.h

@@ -0,0 +1,66 @@
+// `BasaltMenu`: the application menu, from JavaScript.
+//
+// The application menu: `<Menu>` describes one, this installs it, and an item
+// the app owns comes back as a device event carrying its id -- which is the
+// same arrangement the title bar and the window use, for the same reason: a
+// menu item is chosen at a time nothing is waiting for it.
+//
+// And context menus, which are the other kind and answer differently. See
+// `showContextMenu` below.
+//
+// Roles never come back. They are handled where they are: see
+// core/MenuModel.h, and appkit/AppKitMenuBar.mm for the part that makes Cmd-C
+// reach a text field.
+
+#pragma once
+
+#include <ReactCommon/TurboModule.h>
+
+#include <memory>
+
+namespace basalt {
+
+class DesktopMenuModule : public facebook::react::TurboModule {
+ public:
+  static constexpr const char *kModuleName = "BasaltMenu";
+
+  explicit DesktopMenuModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+  ~DesktopMenuModule() override;
+
+ private:
+  // `setApplicationMenu(items)`, where items are the shape core/MenuModel.h
+  // describes. An empty list restores the platform's default.
+  static facebook::jsi::Value setMenu(facebook::jsi::Runtime &runtime,
+                                      facebook::react::TurboModule &module,
+                                      const facebook::jsi::Value *args,
+                                      size_t count);
+  // `isSupported()`: whether this platform puts a menu bar anywhere a person
+  // can see it. False on GNOME, and not a promise to change; see
+  // core/MenuModel.h.
+  static facebook::jsi::Value isSupported(facebook::jsi::Runtime &runtime,
+                                          facebook::react::TurboModule &module,
+                                          const facebook::jsi::Value *args,
+                                          size_t count);
+  // `showContextMenu(items, x, y)` -> a promise of the index chosen, or null
+  // when it was dismissed.
+  //
+  // A promise rather than the device event the application menu uses, and the
+  // difference is worth saying. A menu bar is installed once and its items are
+  // chosen at times nothing is waiting for; a context menu is opened by an app
+  // that is, right then, asking a question -- so the answer belongs to the call
+  // that asked it rather than to a listener somewhere else.
+  static facebook::jsi::Value showContextMenu(facebook::jsi::Runtime &runtime,
+                                              facebook::react::TurboModule &module,
+                                              const facebook::jsi::Value *args,
+                                              size_t count);
+  static facebook::jsi::Value noop(facebook::jsi::Runtime &runtime,
+                                   facebook::react::TurboModule &module,
+                                   const facebook::jsi::Value *args,
+                                   size_t count);
+};
+
+// The device event an item's id arrives on. Named here so the two sides cannot
+// drift.
+inline constexpr const char *kMenuChosenEvent = "basaltMenuItemChosen";
+
+} // namespace basalt