basalt-core 0.0.0-rc5 → 0.1.0

package/native/core/CrashHandler.cpp

@@ -0,0 +1,246 @@
+#include "CrashHandler.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <cstdlib>
+
+#if defined(_WIN32)
+#include <windows.h>
+#else
+#include <csignal>
+#include <execinfo.h>
+#include <pthread.h>
+#include <unistd.h>
+#endif
+
+namespace basalt {
+
+namespace {
+
+#if !defined(_WIN32)
+
+constexpr int kFatalSignals[] = {SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGABRT};
+constexpr std::size_t kFatalSignalCount = sizeof(kFatalSignals) / sizeof(kFatalSignals[0]);
+
+// What was installed before, so each handler can put it back and re-raise. An
+// empty slot is one this never touched.
+struct sigaction gPrevious[kFatalSignalCount];
+
+// The thread that installed the handler, which is the main thread: the handler
+// runs on whichever thread took the signal, and for a hang that is the first
+// thing a reader needs to know. A backtrace that cannot be told apart from the
+// JS thread's is half a diagnosis, which cost a round trip here once already.
+// Recorded rather than derived, because `pthread_main_np` is not portable and
+// `gettid`-style checks say nothing on a host whose main thread is not tid 1.
+pthread_t gMainThread = {};
+bool gMainThreadKnown = false;
+
+int slotFor(int signalNumber) {
+  for (std::size_t i = 0; i < kFatalSignalCount; i++) {
+    if (kFatalSignals[i] == signalNumber) {
+      return static_cast<int>(i);
+    }
+  }
+  return -1;
+}
+
+// Everything below runs in a signal handler, so everything below is
+// async-signal-safe. No allocation, no locks, no formatting.
+
+void writeText(const char *text) {
+  if (text == nullptr) {
+    return;
+  }
+  std::size_t length = 0;
+  while (text[length] != '\0') {
+    length++;
+  }
+  // The result is deliberately ignored: there is nothing useful to do about a
+  // failed write from here, and a partial one still says more than nothing.
+  const ssize_t written = ::write(STDERR_FILENO, text, length);
+  (void)written;
+}
+
+void writeHex(std::uintptr_t value) {
+  char digits[] = "0123456789abcdef";
+  // 16 nibbles, a "0x", and the terminator.
+  char buffer[19];
+  buffer[0] = '0';
+  buffer[1] = 'x';
+  std::size_t at = 2;
+  bool leading = true;
+  for (int shift = 60; shift >= 0; shift -= 4) {
+    const unsigned nibble = static_cast<unsigned>((value >> shift) & 0xF);
+    if (nibble == 0 && leading && shift != 0) {
+      continue;
+    }
+    leading = false;
+    buffer[at++] = digits[nibble];
+  }
+  buffer[at] = '\0';
+  writeText(buffer);
+}
+
+const char *nameFor(int signalNumber) {
+  switch (signalNumber) {
+    case SIGSEGV:
+      return "SIGSEGV";
+    case SIGBUS:
+      return "SIGBUS";
+    case SIGILL:
+      return "SIGILL";
+    case SIGFPE:
+      return "SIGFPE";
+    case SIGABRT:
+      return "SIGABRT";
+    default:
+      return "signal";
+  }
+}
+
+void onFatalSignal(int signalNumber, siginfo_t *info, void * /*context*/) {
+  writeText("\n*** basalt: ");
+  writeText(nameFor(signalNumber));
+  if (info != nullptr) {
+    writeText(" at ");
+    writeHex(reinterpret_cast<std::uintptr_t>(info->si_addr));
+  }
+  // Said plainly, because the whole point is telling the loop apart from JS.
+  // `pthread_equal` on two stored values is a comparison and nothing more, so
+  // it is safe enough here even though it is not on the promised list.
+  if (gMainThreadKnown) {
+    writeText(::pthread_equal(::pthread_self(), gMainThread) != 0
+                  ? ", the main thread"
+                  : ", NOT the main thread");
+  }
+  writeText(", thread ");
+  // The id rather than the name: `pthread_getname_np` takes no lock on either
+  // platform but is not promised to be safe here, and the id is what the glog
+  // lines around this already print.
+  writeHex(static_cast<std::uintptr_t>(
+      reinterpret_cast<std::uintptr_t>(pthread_self())));
+  writeText(" ***\n");
+
+  // 64 frames: deep enough for a mounting walk inside a dispatch block inside a
+  // run loop, which is the stack this was written for.
+  void *frames[64];
+  const int count = ::backtrace(frames, 64);
+  // Writes straight to the descriptor and allocates nothing, unlike
+  // `backtrace_symbols`, which is why it is this one.
+  ::backtrace_symbols_fd(frames, count, STDERR_FILENO);
+  writeText("\n");
+
+  // Back to whatever was there, then re-raise. The exit status stays the signal,
+  // which is what the harness reports, and a handler the runtime installed for
+  // its own purposes still gets its turn.
+  const int slot = slotFor(signalNumber);
+  if (slot >= 0) {
+    ::sigaction(signalNumber, &gPrevious[slot], nullptr);
+  } else {
+    ::signal(signalNumber, SIG_DFL);
+  }
+  ::raise(signalNumber);
+}
+
+#else
+
+LONG WINAPI onUnhandledException(EXCEPTION_POINTERS *info) {
+  // Not a signal handler, so this is allowed more than its POSIX counterpart.
+  // It stays just as narrow anyway: the process is already broken, and a handler
+  // that needs the heap to say so is a handler that says nothing when the heap
+  // is what broke.
+  char line[128];
+  const DWORD code =
+      info != nullptr && info->ExceptionRecord != nullptr
+      ? info->ExceptionRecord->ExceptionCode
+      : 0;
+  const void *at = info != nullptr && info->ExceptionRecord != nullptr
+      ? info->ExceptionRecord->ExceptionAddress
+      : nullptr;
+
+  int length = wsprintfA(line,
+                         "\n*** basalt: exception 0x%08lx at %p, thread %lu ***\n",
+                         static_cast<unsigned long>(code),
+                         at,
+                         GetCurrentThreadId());
+  DWORD written = 0;
+  WriteFile(GetStdHandle(STD_ERROR_HANDLE), line, static_cast<DWORD>(length), &written, nullptr);
+
+  // No symbols: a release build ships no .pdb, so dbghelp would resolve nothing
+  // and linking it would buy an address it already has. The module base is here
+  // so the frames below can be turned into offsets against the binary.
+  length = wsprintfA(line, "module %p\n", static_cast<void *>(GetModuleHandleW(nullptr)));
+  WriteFile(GetStdHandle(STD_ERROR_HANDLE), line, static_cast<DWORD>(length), &written, nullptr);
+
+  void *frames[64];
+  const USHORT count = CaptureStackBackTrace(0, 64, frames, nullptr);
+  for (USHORT i = 0; i < count; i++) {
+    length = wsprintfA(line, "%2u  %p\n", static_cast<unsigned>(i), frames[i]);
+    WriteFile(GetStdHandle(STD_ERROR_HANDLE), line, static_cast<DWORD>(length), &written, nullptr);
+  }
+
+  // On to whatever Windows would have done, so the exit status and any crash
+  // reporting behave as before.
+  return EXCEPTION_CONTINUE_SEARCH;
+}
+
+#endif
+
+} // namespace
+
+namespace {
+
+// BASALT_TEST_CRASH, which exists so that the handler can be tested at all.
+//
+// A handler is only ever exercised on the worst day, so one that was never run
+// is a guess. This makes the worst day reproducible: the scenario in
+// scripts/integration_test.py sets it and asserts the marker, a frame list and an
+// exit status that is still the signal.
+//
+// `raise` rather than writing through a null pointer: a deliberate null
+// dereference is undefined behaviour and a compiler is within its rights to
+// delete it, which would make the test pass by not crashing.
+void crashIfAsked() {
+  const char *value = std::getenv("BASALT_TEST_CRASH");
+  if (value == nullptr || *value == '\0') {
+    return;
+  }
+#if defined(_WIN32)
+  // An access violation, since Windows has no raise(SIGSEGV) worth the name: the
+  // unhandled-exception filter is what is being tested, and only a real exception
+  // reaches it.
+  RaiseException(EXCEPTION_ACCESS_VIOLATION, 0, 0, nullptr);
+#else
+  ::raise(SIGSEGV);
+#endif
+}
+
+} // namespace
+
+void installCrashHandler() {
+#if defined(_WIN32)
+  SetUnhandledExceptionFilter(onUnhandledException);
+  crashIfAsked();
+#else
+  // Once, while allocating is still allowed: glibc's first `backtrace` dlopens
+  // libgcc, and a handler is not the place to find that out.
+  void *warm[1];
+  (void)::backtrace(warm, 1);
+
+  // Called from main() on every host, so this is the main thread.
+  gMainThread = ::pthread_self();
+  gMainThreadKnown = true;
+
+  struct sigaction action = {};
+  action.sa_sigaction = onFatalSignal;
+  action.sa_flags = SA_SIGINFO | SA_ONSTACK;
+  sigemptyset(&action.sa_mask);
+
+  for (std::size_t i = 0; i < kFatalSignalCount; i++) {
+    ::sigaction(kFatalSignals[i], &action, &gPrevious[i]);
+  }
+  crashIfAsked();
+#endif
+}
+
+} // namespace basalt

package/native/core/CrashHandler.h

@@ -0,0 +1,65 @@
+// What the host says when it dies.
+//
+// Written because it had nothing to say. On 2026-10-05 a reload teardown took
+// SIGSEGV on CI's Mac, twice, and three attempts produced no address, no stack
+// and no thread -- only the harness noticing the process was gone and reporting
+// "host exited -11". The bug was found by reading `ReactHost` instead, and the
+// next one will not be as guessable.
+//
+// Deliberately not glog's `InstallFailureSignalHandler`. That would be one line,
+// and its signal list is fixed and includes SIGTERM -- which is how the harness
+// ends a host that is working. A stack trace and a changed exit status there
+// would break the scenarios that read both. See docs/ci-performance.md on
+// BASALT_TEST_QUIT_FILE for what SIGTERM is load-bearing for.
+//
+// ## What it prints
+//
+// To stderr, which is where the harness is already looking:
+//
+//     *** basalt: SIGSEGV at 0x0, thread 0x16dd57000 ***
+//     0   basalt_appkit   0x0000000102a4c1b8 _ZN6basalt19AppKitMountingM...
+//     1   basalt_appkit   0x0000000102a4b9e4 ...
+//
+// The names are mangled, and stay that way: demangling means
+// `abi::__cxa_demangle`, which allocates, and a handler that needs the heap says
+// nothing exactly when the heap is what broke. Pipe the log through `c++filt`.
+//
+// On Windows there are no symbols, for want of a .pdb in a release build, so it
+// prints the module base and the return addresses: subtract the one from the
+// others and the offsets resolve against the binary. Measured on CI, which is
+// the only place this can be:
+//
+//     *** basalt: exception 0xc0000005 at 00007FF92942EFDC, thread 2776 ***
+//     module 00007FF621B00000
+//      0  00007FF621EE0094
+//      1  00007FF9294A05BD
+//
+// Note the shape: `%p` there is upper case and carries no `0x`, unlike
+// `backtrace_symbols_fd` above. Anything reading this output has to take both.
+//
+// ## What it may call
+//
+// Almost nothing. A signal handler may only use async-signal-safe functions, so
+// there is no `LOG()`, no `std::string`, no formatting and no allocation here:
+// glog takes a lock to write a line and a handler that waits for a lock held by
+// the thread it interrupted never returns. `write`, `backtrace_symbols_fd`,
+// `raise` and integer arithmetic are the whole vocabulary.
+//
+// `backtrace` is the exception: on glibc its first call dlopens libgcc, which
+// allocates, so `installCrashHandler` calls it once while that is still safe.
+//
+// @format
+#pragma once
+
+namespace basalt {
+
+// Installs handlers for the signals that mean the process is broken: SIGSEGV,
+// SIGBUS, SIGILL, SIGFPE and SIGABRT. Not SIGTERM and not SIGINT, which mean
+// somebody asked it to stop.
+//
+// Each handler prints, restores whatever was there before, and re-raises, so the
+// exit status is still the signal and anything the runtime installed for its own
+// purposes still runs. Call once, early, after logging is up.
+void installCrashHandler();
+
+} // namespace basalt

package/native/core/CursorNames.h

@@ -0,0 +1,110 @@
+// What a React Native `cursor` value is called, in CSS's own words.
+//
+// The prop is a desktop prop: a hand over a button, an I-beam over text, a
+// resize arrow over a divider. Every host ignored it, and
+// backlog/desktop-capabilities.md said the opposite -- its entry on cursor
+// control described itself as the work left "beyond what the `cursor` style
+// property covers", which nothing covered.
+//
+// ## Why a name rather than a per-host enum
+//
+// React Native's `Cursor` is CSS's keyword list, and so is GDK's: GTK takes the
+// keyword straight through `gtk_widget_set_cursor_from_name`. AppKit has its own
+// small set of NSCursors and maps the names onto it, losing the ones macOS has no
+// cursor for. Keeping the keyword as the thing that crosses the seam means there
+// is one place that says what `cursor: 'grab'` is called and each view layer
+// answers for its own platform, rather than two enums that can drift apart in
+// their middles.
+//
+// Header-only and in core because both mounting managers need it and both know
+// React Native; the view layers do not, and they take a string.
+
+#pragma once
+
+#include <react/renderer/components/view/primitives.h>
+
+namespace basalt {
+
+// The CSS keyword, or nullptr for "nothing to apply" -- which is `auto`, meaning
+// the cursor is whatever the surrounding view says it is, and `url`, which in
+// CSS names a custom image that React Native carries nothing for.
+inline const char *cursorName(facebook::react::Cursor cursor) {
+  using facebook::react::Cursor;
+  switch (cursor) {
+    case Cursor::Auto:
+      return nullptr;
+    case Cursor::Alias:
+      return "alias";
+    case Cursor::AllScroll:
+      return "all-scroll";
+    case Cursor::Cell:
+      return "cell";
+    case Cursor::ColResize:
+      return "col-resize";
+    case Cursor::ContextMenu:
+      return "context-menu";
+    case Cursor::Copy:
+      return "copy";
+    case Cursor::Crosshair:
+      return "crosshair";
+    case Cursor::Default:
+      return "default";
+    case Cursor::EResize:
+      return "e-resize";
+    case Cursor::EWResize:
+      return "ew-resize";
+    case Cursor::Grab:
+      return "grab";
+    case Cursor::Grabbing:
+      return "grabbing";
+    case Cursor::Help:
+      return "help";
+    case Cursor::Move:
+      return "move";
+    case Cursor::NEResize:
+      return "ne-resize";
+    case Cursor::NESWResize:
+      return "nesw-resize";
+    case Cursor::NResize:
+      return "n-resize";
+    case Cursor::NSResize:
+      return "ns-resize";
+    case Cursor::NWResize:
+      return "nw-resize";
+    case Cursor::NWSEResize:
+      return "nwse-resize";
+    case Cursor::NoDrop:
+      return "no-drop";
+    case Cursor::None:
+      return "none";
+    case Cursor::NotAllowed:
+      return "not-allowed";
+    case Cursor::Pointer:
+      return "pointer";
+    case Cursor::Progress:
+      return "progress";
+    case Cursor::RowResize:
+      return "row-resize";
+    case Cursor::SResize:
+      return "s-resize";
+    case Cursor::SEResize:
+      return "se-resize";
+    case Cursor::SWResize:
+      return "sw-resize";
+    case Cursor::Text:
+      return "text";
+    case Cursor::Url:
+      return nullptr;
+    case Cursor::WResize:
+      return "w-resize";
+    case Cursor::Wait:
+      return "wait";
+    case Cursor::ZoomIn:
+      return "zoom-in";
+    case Cursor::ZoomOut:
+      return "zoom-out";
+  }
+  return nullptr;
+}
+
+} // namespace basalt

package/native/core/DevMenu.cpp

@@ -73,11 +73,12 @@ void showDevMenu(facebook::react::ReactHost *reactHost, double x, double y) {
   request.y = y;
   request.entries.reserve(items->size());
   for (const DevMenuItem &item : *items) {
-    request.entries.push_back(MenuEntry{
-        .label = item.label,
-        .enabled = true,
-        .shortcut = item.shortcut,
-    });
+    // Assigned, not a designated initializer: see MenuEntry::separator for why
+    // naming some fields and not others does not survive a new one.
+    MenuEntry entry;
+    entry.label = item.label;
+    entry.shortcut = item.shortcut;
+    request.entries.push_back(std::move(entry));
   }
 
   // Through presentMenu rather than showMenu, so BASALT_TEST_MENU can answer

package/native/core/DeviceMetrics.cpp

@@ -0,0 +1,87 @@
+#include "DeviceMetrics.h"
+
+#include "FontScaling.h"
+
+namespace basalt {
+
+namespace {
+
+// Which display a point is on, or nothing when no display contains it -- a
+// window dragged to a monitor that has just been unplugged, or a host that has
+// reported no displays at all.
+const DisplayInfo *displayContaining(const std::vector<DisplayInfo> &displays,
+                                     double x,
+                                     double y) {
+  for (const DisplayInfo &display : displays) {
+    if (x >= display.x && x < display.x + display.width && y >= display.y &&
+        y < display.y + display.height) {
+      return &display;
+    }
+  }
+  return nullptr;
+}
+
+const DisplayInfo *primaryDisplay(const std::vector<DisplayInfo> &displays) {
+  for (const DisplayInfo &display : displays) {
+    if (display.primary) {
+      return &display;
+    }
+  }
+  return displays.empty() ? nullptr : &displays.front();
+}
+
+} // namespace
+
+DeviceMetrics deviceMetricsFrom(const WindowBounds &window,
+                                double surfaceWidth,
+                                double surfaceHeight,
+                                const std::vector<DisplayInfo> &displays,
+                                double fontScale) {
+  const double scale = fontScale > 0.0 ? fontScale : 1.0;
+
+  // The display the window's centre is on, falling back to the primary one: a
+  // window that has not been placed yet is at the origin, which is the primary
+  // display's corner on every host.
+  const DisplayInfo *on = displayContaining(displays,
+                                            window.x + window.width / 2.0,
+                                            window.y + window.height / 2.0);
+  if (on == nullptr) {
+    on = primaryDisplay(displays);
+  }
+
+  DeviceMetrics metrics;
+  metrics.window.scale = on != nullptr && on->scaleFactor > 0.0 ? on->scaleFactor : 1.0;
+  metrics.window.fontScale = scale;
+  // The surface when the host has started one, which is the area an app can
+  // lay out in; the window's frame otherwise.
+  metrics.window.width = surfaceWidth > 0.0 ? surfaceWidth : window.width;
+  metrics.window.height = surfaceHeight > 0.0 ? surfaceHeight : window.height;
+
+  metrics.screen = metrics.window;
+  if (on != nullptr) {
+    metrics.screen.width = on->width;
+    metrics.screen.height = on->height;
+  }
+
+  // Nothing reported yet. The screen is a better answer than zero for an app
+  // laying out during its first render; see the header.
+  if (metrics.window.width <= 0.0 || metrics.window.height <= 0.0) {
+    metrics.window.width = metrics.screen.width;
+    metrics.window.height = metrics.screen.height;
+  }
+
+  return metrics;
+}
+
+DeviceMetrics currentDeviceMetrics() {
+  double surfaceWidth = 0.0;
+  double surfaceHeight = 0.0;
+  lastKnownSurfaceSize(&surfaceWidth, &surfaceHeight);
+  return deviceMetricsFrom(lastKnownWindowBounds(),
+                           surfaceWidth,
+                           surfaceHeight,
+                           lastKnownDisplays(),
+                           static_cast<double>(systemFontScale()));
+}
+
+} // namespace basalt

package/native/core/DeviceMetrics.h

@@ -0,0 +1,80 @@
+// What `Dimensions` and `PixelRatio` answer with.
+//
+// React Native's `Dimensions.get('window')` is one of the most-used APIs it
+// has, and on this platform it reported a fiction: ReactCxxPlatform's
+// `DeviceInfoModule::getConstants` returns a hardcoded 1280x720 with a
+// `// TODO: Wire this to come from the actual app size` beside it and no seam
+// to wire. `scale` came back 0 and `fontScale` was never initialised at all --
+// the generated struct leaves it so -- which made `PixelRatio.get()` zero and
+// `PixelRatio.roundToNearestPixel(x)` NaN, silently, in every app.
+//
+// Everything needed is already here: `lastKnownWindowBounds()` is the window
+// the host reports on every change, `lastKnownDisplays()` carries each
+// display's scale factor, and `systemFontScale()` is the text scale the font
+// machinery already multiplies by. This is the arithmetic that turns the three
+// into React Native's two payloads, written once so three hosts cannot
+// disagree about which display a window is on.
+
+#pragma once
+
+#include "WindowControl.h"
+
+#include <vector>
+
+namespace basalt {
+
+// One of React Native's `DisplayMetrics`: a size in logical pixels, how many
+// physical pixels each of those is, and the text scale.
+struct DisplayMetrics {
+  double width{0.0};
+  double height{0.0};
+  // Never zero. A caller dividing by it -- which is exactly what
+  // `PixelRatio.roundToNearestPixel` does -- should not have to check.
+  double scale{1.0};
+  double fontScale{1.0};
+};
+
+struct DeviceMetrics {
+  DisplayMetrics window;
+  DisplayMetrics screen;
+
+  bool operator==(const DeviceMetrics &other) const {
+    return window.width == other.window.width && window.height == other.window.height &&
+        window.scale == other.window.scale && window.fontScale == other.window.fontScale &&
+        screen.width == other.screen.width && screen.height == other.screen.height &&
+        screen.scale == other.screen.scale && screen.fontScale == other.screen.fontScale;
+  }
+  bool operator!=(const DeviceMetrics &other) const { return !(*this == other); }
+};
+
+// The window and the screen it is on, from what the host has reported.
+//
+// `window` is the window's own size; `screen` is the display it sits on, which
+// is the distinction React Native draws and which matters on a desktop in a way
+// it never does on a phone: a window is a fraction of a screen, and an app
+// deciding how much it can show wants the first while one deciding where to put
+// itself wants the second.
+//
+// Which display a window is on is decided by its centre, so a window straddling
+// two reports the one most of it is on. A window the host has not reported yet
+// -- everything is zero -- borrows the primary display's size rather than
+// reporting a zero an app would divide by; that is the first render, before the
+// first layout, and a zero there is worse than an estimate.
+// `surfaceWidth` and `surfaceHeight` are the area React lays out in, which is
+// what `window` reports when it is known: a desktop window's frame includes a
+// title bar the app cannot put anything in, and the two differ by exactly that
+// on AppKit. Zero means the host has not started a surface yet, and then the
+// window's own size is used instead.
+DeviceMetrics deviceMetricsFrom(const WindowBounds &window,
+                                double surfaceWidth,
+                                double surfaceHeight,
+                                const std::vector<DisplayInfo> &displays,
+                                double fontScale);
+
+// The same, from what the host last reported and what the font machinery is
+// scaling by. Safe from any thread, which is the point: a TurboModule method
+// runs on the JavaScript thread and the toolkit may only be asked on the UI
+// one.
+DeviceMetrics currentDeviceMetrics();
+
+} // namespace basalt