basalt-core 0.0.0-rc5

package/native/cmake/ThirdParty.cmake

@@ -0,0 +1,290 @@
+# Provides the third-party CMake target *names* React Native's own CMakeLists
+# link against, backed by system packages where possible and by vendored
+# sources where not.
+#
+# React Native normally gets these from its Android build (gradle downloads and
+# unpacks each one under third-party-ndk). A host build has no such step, so we
+# supply equivalents here. Fantom does the same thing for its tester.
+#
+# Two ways of finding the same four libraries, and the split is Windows.
+#
+# On Linux and macOS they come from the system -- apt or Homebrew -- and
+# `find_library` is the right tool, because a distro's package installs a bare
+# `libglog.so` in a directory the linker already searches. On Windows there is
+# no system to install them into. vcpkg is the equivalent, and it ships proper
+# CMake config packages, which is a better answer than `find_library` even
+# where both would work: a config package carries the include directories, the
+# transitive dependencies and the debug/release split, and a bare
+# `find_library` on `boost_regex` would not even match the name vcpkg gives it
+# (`boost_regex-vc143-mt-x64-1_89.lib`).
+#
+# The target names below -- `glog`, `boost`, `double-conversion`, `fmt` -- are
+# not ours to choose either way. They are what React Native's own CMakeLists
+# link against.
+if(WIN32)
+  find_package(glog CONFIG REQUIRED)
+  find_package(Boost CONFIG REQUIRED COMPONENTS regex thread)
+  find_package(double-conversion CONFIG REQUIRED)
+  find_package(fmt CONFIG REQUIRED)
+
+  # React Native's CMakeLists link the bare names; vcpkg's config packages
+  # define namespaced ones. These INTERFACE targets stand in the middle.
+  # Guarded on the name not already existing, because a config package is
+  # entitled to define the bare name too and CMake refuses a duplicate.
+  if(NOT TARGET glog)
+    add_library(glog INTERFACE)
+    target_link_libraries(glog INTERFACE glog::glog)
+  endif()
+  target_compile_definitions(glog INTERFACE GLOG_USE_GLOG_EXPORT)
+
+  add_library(boost INTERFACE)
+  # Boost::thread as well as regex: folly's Windows PThread.cpp is written over
+  # boost::thread, and its thread-local storage needs the compiled library
+  # rather than the headers.
+  target_link_libraries(boost INTERFACE Boost::regex Boost::thread Boost::headers)
+
+  if(NOT TARGET double-conversion)
+    add_library(double-conversion INTERFACE)
+    target_link_libraries(double-conversion INTERFACE double-conversion::double-conversion)
+  endif()
+
+  if(NOT TARGET fmt)
+    add_library(fmt INTERFACE)
+    target_link_libraries(fmt INTERFACE fmt::fmt)
+  endif()
+
+  # As on the other platforms: nothing on a host build needs glog's signal
+  # handlers, and React Native's Android build is the only thing that has them.
+  add_library(glog_init INTERFACE)
+else()
+
+# --- glog ------------------------------------------------------------------
+# RN pins glog 0.3.5; distros ship 0.7.x, which added a guard requiring
+# GLOG_USE_GLOG_EXPORT when the headers are not consumed via glog's own CMake
+# target. Without it every glog header hard-errors.
+find_library(GLOG_LIBRARY glog REQUIRED)
+find_path(GLOG_INCLUDE_DIR glog/logging.h REQUIRED)
+add_library(glog INTERFACE)
+target_link_libraries(glog INTERFACE ${GLOG_LIBRARY})
+# Distros put headers in /usr/include; Homebrew does not, so carry the path.
+target_include_directories(glog INTERFACE ${GLOG_INCLUDE_DIR})
+target_compile_definitions(glog INTERFACE GLOG_USE_GLOG_EXPORT)
+
+# RN's Android build has a glog_init target that installs signal handlers.
+# Nothing on a host build needs it; Fantom stubs it the same way.
+add_library(glog_init INTERFACE)
+
+# --- boost -----------------------------------------------------------------
+# Headers only, with one exception: folly's Uri parser uses boost::regex, which
+# is a compiled library. Uri is pulled in by React Native's websocket client
+# (see rn_websocket in ReactNativeCore.cmake), so it is needed as soon as the
+# dev server is. boost::asio and boost::beast, which that client also uses, are
+# header-only.
+find_path(BOOST_INCLUDE_DIR boost/version.hpp REQUIRED)
+find_library(BOOST_REGEX_LIBRARY NAMES boost_regex boost_regex-mt REQUIRED)
+add_library(boost INTERFACE)
+target_include_directories(boost INTERFACE ${BOOST_INCLUDE_DIR})
+target_link_libraries(boost INTERFACE ${BOOST_REGEX_LIBRARY})
+
+# --- double-conversion -----------------------------------------------------
+find_library(DOUBLE_CONVERSION_LIBRARY double-conversion REQUIRED)
+find_path(DOUBLE_CONVERSION_INCLUDE_DIR double-conversion/double-conversion.h REQUIRED)
+add_library(double-conversion INTERFACE)
+target_link_libraries(double-conversion INTERFACE ${DOUBLE_CONVERSION_LIBRARY})
+target_include_directories(double-conversion INTERFACE ${DOUBLE_CONVERSION_INCLUDE_DIR})
+
+# --- fmt -------------------------------------------------------------------
+find_library(FMT_LIBRARY fmt REQUIRED)
+find_path(FMT_INCLUDE_DIR fmt/format.h REQUIRED)
+add_library(fmt INTERFACE)
+target_link_libraries(fmt INTERFACE ${FMT_LIBRARY})
+target_include_directories(fmt INTERFACE ${FMT_INCLUDE_DIR})
+
+endif() # WIN32 -- everything below is the same on all three platforms.
+
+# --- fast_float (vendored, header-only) ------------------------------------
+add_library(fast_float INTERFACE)
+target_include_directories(fast_float INTERFACE ${FAST_FLOAT_DIR}/include)
+
+# --- folly_runtime ---------------------------------------------------------
+# The trimmed folly RN actually builds: ~30 translation units, no config step,
+# no coroutines. Source list and flags mirror
+# private/react-native-fantom/tester/third-party/folly/CMakeLists.txt.
+# Three of these are claims about POSIX and are false on Windows. folly reads
+# them as "the platform has this", not as "please provide it", so leaving them
+# defined on Windows makes it call recvmmsg, pthread_setname_np and the XSI
+# strerror_r, none of which exist -- and it fails at link rather than at
+# configure, which is a worse place to find out.
+#
+# FOLLY_HAVE_CLOCK_GETTIME is the interesting one. Windows has no
+# clock_gettime, but folly's portability layer *provides* one, and defining the
+# flag is how folly is told to use its own rather than expect the system's.
+set(folly_FLAGS
+        -DFOLLY_NO_CONFIG=1
+        -DFOLLY_HAVE_CLOCK_GETTIME=1
+        -DFOLLY_CFG_NO_COROUTINES=1
+        -DFOLLY_MOBILE=0)
+if(NOT WIN32)
+  list(APPEND folly_FLAGS
+        -DFOLLY_HAVE_RECVMMSG=1
+        -DFOLLY_HAVE_PTHREAD=1
+        -DFOLLY_HAVE_XSI_STRERROR_R=1)
+endif()
+
+set(folly_runtime_SRC
+        Conv.cpp Demangle.cpp FileUtil.cpp Format.cpp ScopeGuard.cpp
+        SharedMutex.cpp String.cpp Unicode.cpp
+        concurrency/CacheLocality.cpp
+        container/detail/F14Table.cpp
+        detail/FileUtilDetail.cpp detail/Futex.cpp
+        detail/SplitStringSimd.cpp detail/UniqueInstance.cpp
+        hash/SpookyHashV2.cpp
+        io/IOBuf.cpp
+        json/dynamic.cpp json/json_pointer.cpp json/json.cpp
+        # Not in React Native's own folly source list. Its websocket client
+        # parses the packager URL with folly::Uri, so a host that talks to the
+        # dev server needs it.
+        Uri.cpp
+        lang/CString.cpp lang/Exception.cpp lang/SafeAssert.cpp lang/ToAscii.cpp
+        memory/SanitizeAddress.cpp memory/detail/MallocImpl.cpp
+        net/NetOps.cpp
+        portability/SysUio.cpp
+        synchronization/SanitizeThread.cpp synchronization/ParkingLot.cpp
+        system/AtFork.cpp system/ThreadId.cpp system/ThreadName.cpp)
+# folly's Windows portability layer, which React Native's own source list does
+# not carry because React Native does not build folly on Windows -- it consumes
+# a prebuilt one. These are not shims this project wrote: nineteen of folly's
+# twenty-one portability sources already have `_WIN32` branches, and this is the
+# subset the translation units above reach. Without them the build gets all the
+# way to the linker and fails on `open`, `pthread_key_create`, `gettimeofday`
+# and thirty more.
+if(WIN32)
+  list(APPEND folly_runtime_SRC
+        portability/Dirent.cpp
+        portability/Fcntl.cpp
+        portability/Malloc.cpp
+        portability/PThread.cpp
+        portability/Sched.cpp
+        portability/Sockets.cpp
+        portability/Stdio.cpp
+        portability/Stdlib.cpp
+        portability/String.cpp
+        portability/SysFile.cpp
+        portability/SysMembarrier.cpp
+        portability/SysMman.cpp
+        portability/SysResource.cpp
+        portability/SysStat.cpp
+        portability/SysTime.cpp
+        portability/Time.cpp
+        portability/Unistd.cpp
+        # Not under portability/: folly keeps its Windows socket-handle table in
+        # net/detail. Without it the link fails on SocketFileDescriptorMap, which
+        # is what folly::netops uses to make a SOCKET look like an fd.
+        net/detail/SocketFileDescriptorMap.cpp)
+endif()
+
+list(TRANSFORM folly_runtime_SRC PREPEND ${FOLLY_DIR}/folly/)
+
+add_library(folly_runtime STATIC ${folly_runtime_SRC})
+target_compile_options(folly_runtime PRIVATE
+        ${BASALT_EXCEPTIONS_FLAG} ${BASALT_FRAME_POINTER_FLAG} ${BASALT_RTTI_FLAG}
+        ${BASALT_NO_SIGN_COMPARE_FLAG} ${folly_FLAGS})
+target_compile_options(folly_runtime PUBLIC ${folly_FLAGS})
+if(WIN32)
+  # ws2_32 for the sockets folly's net layer wraps, and NOMINMAX because folly
+  # uses std::min and std::max in headers that windows.h has already redefined
+  # as macros by the time they are reached.
+  # winmm for timeBeginPeriod/timeEndPeriod, which folly's Windows clock uses to
+  # ask for a finer timer resolution.
+  target_link_libraries(folly_runtime ws2_32 winmm)
+  target_compile_definitions(folly_runtime PUBLIC NOMINMAX WIN32_LEAN_AND_MEAN)
+endif()
+target_include_directories(folly_runtime PUBLIC ${FOLLY_DIR})
+target_link_libraries(folly_runtime glog double-conversion boost fmt fast_float)
+
+# --- nlohmann_json (vendored, header-only) ---------------------------------
+# Needed by ReactCxxPlatform's devsupport (PackagerConnection).
+add_library(nlohmann_json INTERFACE)
+target_include_directories(nlohmann_json INTERFACE ${NLOHMANN_JSON_DIR}/include)
+
+# --- OpenSSL ---------------------------------------------------------------
+# Also devsupport: the packager connection speaks WebSocket over TLS.
+find_package(OpenSSL REQUIRED)
+
+# --- libcurl ---------------------------------------------------------------
+# Backs src/LinuxNetworking.cpp's IHttpClient: the dev server bundle fetch and
+# NetworkingModule (fetch/XHR) both go through it. Present on macOS in the SDK;
+# on Linux it is the curl development package.
+find_package(CURL REQUIRED)
+
+# --- Hermes ----------------------------------------------------------------
+# Built separately from RN's pinned tarball; see README. Fantom locates the
+# same library out of its Android hermes-engine build dir.
+# Two names, because Hermes renamed the library. React Native 0.81's Hermes
+# builds `libhermes`; the one 0.87 and main use builds `libhermesvm`. Which one
+# is present follows from the version in supported-versions.json, so this looks
+# for either rather than being told.
+find_library(HERMES_VM_LIBRARY NAMES hermesvm hermes
+  HINTS ${HERMES_BUILD_DIR}/API/hermes ${HERMES_BUILD_DIR}/lib
+  REQUIRED)
+
+# Two things about Hermes on Windows that follow from static archives not
+# behaving like shared libraries, and neither of which is visible elsewhere.
+#
+# First, the name found above is wrong here. Hermes' `hermesvm` target builds a
+# DLL, and a Windows DLL exports nothing without __declspec(dllexport), which
+# Hermes does not annotate -- so `hermesvm.lib` is a one-kilobyte import library
+# for a DLL with nothing in it, next to a thirty-megabyte `hermesvm_a.lib` that
+# has the engine. On Linux the shared object works because ELF exports
+# everything by default; that default is the only reason the name is right
+# there.
+#
+# Second, jsi has to be named separately. `-DJSI_DIR` makes the Hermes build
+# compile React Native's jsi, and on Linux libhermesvm.so absorbs it the way a
+# shared library absorbs its static dependencies. A static archive absorbs
+# nothing, so on Windows jsi.lib is a second file and the link fails on
+# jsi::Value and jsi::JSError without it.
+if(WIN32)
+  find_library(HERMES_VM_STATIC_LIBRARY NAMES hermesvm_a
+    HINTS ${HERMES_BUILD_DIR}/lib REQUIRED)
+  find_library(HERMES_JSI_LIBRARY NAMES jsi
+    HINTS ${HERMES_BUILD_DIR}/jsi REQUIRED)
+  # And ICU. Hermes reports "Using Windows 10 built-in ICU" at configure time
+  # and defines USE_WIN10_ICU, which means it calls u_strToUpper, ucol_strcoll
+  # and friends out of the operating system's own icu.dll rather than vendoring
+  # a copy. `icu.lib` is that DLL's import library and ships with the Windows
+  # SDK. Nothing names it for us: on Linux the equivalent arrives through
+  # pkg-config, and on a shared-library platform it would have been recorded as
+  # a dependency of libhermesvm.so.
+  set(HERMES_LINK_LIBRARIES
+    ${HERMES_VM_STATIC_LIBRARY} ${HERMES_JSI_LIBRARY} icu)
+else()
+  set(HERMES_LINK_LIBRARIES ${HERMES_VM_LIBRARY})
+endif()
+# Both names, for the same reason the find_library above takes both: React
+# Native 0.81's own CMakeLists link hermes-engine::libhermes, and 0.87 and main
+# link hermes-engine::hermesvm. Only one of them is ever referenced by a given
+# React Native, and defining the other costs nothing.
+# GLOBAL because the platform packages are separate directories now: an
+# imported target is visible only in the directory that created it and below,
+# and basalt-gtk adds this one as a *sibling* subdirectory rather
+# than containing it. Without GLOBAL the failure is "target was not found" at
+# generate time, naming the target and not the scope.
+foreach(hermes_alias hermesvm libhermes)
+  add_library(hermes-engine::${hermes_alias} INTERFACE IMPORTED GLOBAL)
+  # Quoted, because on Windows this is two libraries rather than one and an
+  # unquoted list would arrive as extra arguments to set_target_properties.
+  set_target_properties(hermes-engine::${hermes_alias} PROPERTIES
+    INTERFACE_LINK_LIBRARIES "${HERMES_LINK_LIBRARIES}")
+endforeach()
+
+# Hermes' public headers must be globally visible: RN's own hermes/executor and
+# hermes/inspector-modern targets include <hermes/hermes.h> without declaring a
+# dependency that would carry the path. Fantom does the same with a global
+# include_directories() over its prefab-headers dir.
+#
+# RN's jsi is used rather than Hermes' vendored copy, so API/ and public/ only.
+include_directories(
+  ${HERMES_DIR}/API
+  ${HERMES_DIR}/public
+  ${HERMES_BUILD_DIR}/lib/config)

package/native/cmake/Worklets.cmake

@@ -0,0 +1,67 @@
+# react-native-worklets, compiled from the app's own copy.
+#
+# The same arrangement as Expo.cmake and for the same reason: the package ships
+# its portable half as C++ in `Common/cpp`, depending on jsi, Hermes, a call
+# invoker and nothing else, so the app's own copy compiles at the app's own
+# version. Nothing is vendored and nothing is pinned.
+#
+# What the package does *not* ship for a desktop is the host half -- the
+# TurboModule, the UI scheduler, the frame queue and the platform logger are
+# written per platform, and iOS's and Android's are a few hundred lines each.
+# Those are core/Worklets*.{h,cpp} here.
+#
+# Reanimated sits on top of this and is the same shape again; see
+
+if(NOT DEFINED BASALT_WORKLETS)
+  return()
+endif()
+
+get_filename_component(WORKLETS_DIR "${BASALT_WORKLETS}" ABSOLUTE)
+set(WORKLETS_CPP_DIR ${WORKLETS_DIR}/Common/cpp)
+
+if(NOT EXISTS ${WORKLETS_CPP_DIR}/worklets/WorkletRuntime/WorkletRuntime.cpp)
+  message(FATAL_ERROR
+          "no react-native-worklets C++ at ${WORKLETS_CPP_DIR}.\n"
+          "BASALT_WORKLETS should name an installed react-native-worklets, "
+          "the one in the app's node_modules.")
+endif()
+
+# The version the package declares, which its C++ compares against the version
+# its JavaScript declares and warns about when they differ. Read from the
+# package rather than pinned, for the same reason everything else here is.
+file(READ ${WORKLETS_DIR}/package.json WORKLETS_PACKAGE_JSON)
+string(JSON WORKLETS_VERSION GET "${WORKLETS_PACKAGE_JSON}" version)
+
+file(GLOB_RECURSE WORKLETS_SRC CONFIGURE_DEPENDS ${WORKLETS_CPP_DIR}/worklets/*.cpp)
+
+add_library(worklets_core OBJECT ${WORKLETS_SRC})
+# SYSTEM, and warnings off: somebody else's sources held to somebody else's
+# warning set. This project's -Wall -Wextra -Werror is about its own code.
+target_include_directories(worklets_core SYSTEM PUBLIC
+        ${WORKLETS_CPP_DIR}
+        ${RN_DIR}/ReactCommon
+        ${RN_DIR}/ReactCommon/jsi
+        ${RN_DIR}/ReactCommon/callinvoker
+        ${RN_DIR}/ReactCommon/cxxreact
+        ${RN_DIR}/ReactCommon/jsiexecutor
+        ${RN_DIR}/ReactCommon/runtimeexecutor
+        ${FOLLY_DIR})
+target_compile_options(worklets_core PRIVATE -w)
+target_compile_definitions(worklets_core PUBLIC
+        WORKLETS_VERSION=${WORKLETS_VERSION}
+        WORKLETS_FEATURE_FLAGS=\"\")
+target_link_libraries(worklets_core folly_runtime glog hermes-engine::hermesvm)
+if(APPLE)
+  # AsyncQueueImpl wraps each job in an autorelease pool on Apple platforms,
+  # which is right and needs the Objective-C runtime -- even for the GTK host,
+  # which is built on macOS here and is otherwise pure C++.
+  target_link_libraries(worklets_core "-framework Foundation")
+endif()
+
+message(STATUS "Worklets from ${WORKLETS_DIR}")
+
+# Not add_compile_definitions: that is directory-scoped, and the hosts are
+# sibling directories since the packages were split, so they would compile
+# without it and quietly not offer the module. It goes on basalt_core as PUBLIC
+# instead, where linking carries it -- the same fix BASALT_RN_MINOR needed.
+# See the target_compile_definitions beside basalt_core in ../CMakeLists.txt.

package/native/cmake/codegen/CMakeLists.txt

@@ -0,0 +1,32 @@
+# Replaces the CMakeLists that generate-codegen-artifacts.js emits alongside
+# the generated sources, which links Android-only targets (fbjni,
+# turbomodulejsijni). Mirrors private/react-native-fantom/tester/codegen/
+# CMakeLists.txt. bootstrap.sh regenerates the sources around this file and
+# must not overwrite it.
+
+cmake_minimum_required(VERSION 3.13)
+
+# Only the Fabric component specs. The top-level FBReactNativeSpec-generated.cpp
+# is the JNI TurboModule binding and includes ReactCommon/JavaTurboModule.h,
+# which is Android-only. Fantom excludes it the same way.
+file(GLOB react_codegen_SRCS CONFIGURE_DEPENDS
+  react/renderer/components/FBReactNativeSpec/*.cpp)
+
+add_library(react_codegen_rncore OBJECT ${react_codegen_SRCS})
+
+target_include_directories(react_codegen_rncore PUBLIC
+  ${CMAKE_CURRENT_SOURCE_DIR}
+  ${CMAKE_CURRENT_SOURCE_DIR}/react/renderer/components/FBReactNativeSpec
+  ${CMAKE_CURRENT_SOURCE_DIR}/react/renderer/components)
+
+target_link_libraries(react_codegen_rncore
+  jsi
+  react_nativemodule_core
+  rrc_view)
+
+target_compile_options(react_codegen_rncore PRIVATE
+  -DLOG_TAG=\"ReactNative\"
+  -fexceptions
+  -frtti
+  -std=c++20
+  -Wall)

package/native/core/AppIdentity.cpp

@@ -0,0 +1,85 @@
+#include "AppIdentity.h"
+
+#include <folly/json.h>
+
+#include <filesystem>
+#include <fstream>
+#include <mutex>
+#include <sstream>
+
+namespace basalt {
+
+namespace {
+
+AppIdentity &storage() {
+  static AppIdentity identity;
+  return identity;
+}
+
+std::once_flag &readOnce() {
+  static std::once_flag flag;
+  return flag;
+}
+
+AppIdentity readFrom(const std::string &bundlePath) {
+  AppIdentity identity;
+
+  std::error_code error;
+  const std::filesystem::path bundle(bundlePath);
+  const std::filesystem::path file =
+      (bundle.has_parent_path() ? bundle.parent_path() : std::filesystem::current_path(error)) /
+      "app.identity.json";
+
+  std::ifstream stream(file);
+  if (!stream) {
+    return identity;
+  }
+  std::stringstream contents;
+  contents << stream.rdbuf();
+
+  try {
+    const folly::dynamic parsed = folly::parseJson(contents.str());
+    if (!parsed.isObject()) {
+      return identity;
+    }
+    if (const auto *name = parsed.get_ptr("name"); name != nullptr && name->isString()) {
+      identity.name = name->asString();
+    }
+    if (const auto *id = parsed.get_ptr("identifier"); id != nullptr && id->isString()) {
+      identity.identifier = id->asString();
+    }
+    if (const auto *version = parsed.get_ptr("version"); version != nullptr && version->isString()) {
+      identity.version = version->asString();
+    }
+    if (const auto *schemes = parsed.get_ptr("schemes"); schemes != nullptr && schemes->isArray()) {
+      for (const auto &scheme : *schemes) {
+        if (scheme.isString()) {
+          identity.schemes.push_back(scheme.asString());
+        }
+      }
+    }
+  } catch (const std::exception &) {
+    // A malformed file is the same as none. It is written by this project's own
+    // CLI, so a parse failure means somebody edited it by hand -- and refusing
+    // to start over it would be a worse answer than starting without an icon.
+    return AppIdentity{};
+  }
+  return identity;
+}
+
+} // namespace
+
+AppIdentity readAppIdentity(const std::string &bundlePath) {
+  return readFrom(bundlePath);
+}
+
+const AppIdentity &appIdentity(const std::string &bundlePath) {
+  std::call_once(readOnce(), [&bundlePath] { storage() = readFrom(bundlePath); });
+  return storage();
+}
+
+const AppIdentity &appIdentity() {
+  return storage();
+}
+
+} // namespace basalt

package/native/core/AppIdentity.h

@@ -0,0 +1,59 @@
+// What the app calls itself, as the desktop needs to know it.
+//
+// A host is a generic binary: it is handed a bundle and a module name and has
+// no idea what application it is. That is fine for drawing and not fine for
+// anything the operating system keys on identity -- a notification's name and
+// icon, a taskbar group, a registered URL scheme.
+//
+// `cli/packageApp.js` writes the answer beside the bundle as `app.identity.json`
+// and this reads it. Beside the bundle rather than beside the executable
+// because the executable is shared by every app on the machine, and beside it
+// rather than passed as an argument because a shortcut the person clicks in a
+// month has no environment to carry one.
+//
+// Everything here degrades rather than fails: an app built by hand, with no
+// identity file, gets an empty identity, and each caller decides what that
+// means. Windows treats it as "no AppUserModelID, so no toasts", which is the
+// same answer it gave before any of this existed.
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+struct AppIdentity {
+  // What a person sees: "The Demo".
+  std::string name;
+  // Reverse-DNS, and on Windows also the AppUserModelID: "com.example.demo".
+  std::string identifier;
+  // URL schemes the app claims, without the "://".
+  std::vector<std::string> schemes;
+  std::string version;
+
+  bool empty() const {
+    return identifier.empty();
+  }
+};
+
+// Reads `app.identity.json` from beside `bundlePath`, with no caching. Returns
+// an empty identity when there is none, when it cannot be parsed, or when it
+// says nothing useful -- none of which is an error.
+//
+// Separate from the cached reader below so that it can be tested: the cache is
+// process-wide and answers once, which a test cannot work with.
+AppIdentity readAppIdentity(const std::string &bundlePath);
+
+// Reads `app.identity.json` from beside `bundlePath`. Returns an empty identity
+// when there is none, which is not an error.
+//
+// Read once and cached: it is consulted from startup and from the notification
+// path, and it cannot change under a running process.
+const AppIdentity &appIdentity(const std::string &bundlePath);
+
+// The identity read earlier, or an empty one when nothing has read it yet.
+// For the callers that have no bundle path in reach.
+const AppIdentity &appIdentity();
+
+} // namespace basalt

package/native/core/AppPaths.cpp

@@ -0,0 +1,96 @@
+#include "AppPaths.h"
+
+#include <cstdint>
+#include <filesystem>
+#include <string>
+#include <utility>
+
+#if defined(__APPLE__)
+#include <mach-o/dyld.h>
+#elif defined(_WIN32)
+#include <windows.h>
+#endif
+
+namespace basalt {
+
+namespace {
+
+// The running executable, by each platform's own way of asking. There is no
+// portable one: argv[0] is whatever the caller passed and may be a bare name.
+std::string executablePath() {
+#if defined(__APPLE__)
+  uint32_t size = 0;
+  _NSGetExecutablePath(nullptr, &size);
+  std::string buffer(size, '\0');
+  if (_NSGetExecutablePath(buffer.data(), &size) != 0) {
+    return {};
+  }
+  // Sized to include the terminator, so the string has one inside it.
+  return buffer.c_str();
+#elif defined(_WIN32)
+  std::wstring buffer(MAX_PATH, L'\0');
+  DWORD length = GetModuleFileNameW(nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
+  while (length == buffer.size()) {
+    // The path was longer than the buffer, which GetModuleFileNameW reports by
+    // filling it exactly; there is no other way to ask how long it is.
+    buffer.resize(buffer.size() * 2);
+    length = GetModuleFileNameW(nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
+  }
+  if (length == 0) {
+    return {};
+  }
+  buffer.resize(length);
+  const int bytes = WideCharToMultiByte(
+      CP_UTF8, 0, buffer.c_str(), static_cast<int>(buffer.size()), nullptr, 0, nullptr, nullptr);
+  if (bytes <= 0) {
+    return {};
+  }
+  std::string utf8(static_cast<size_t>(bytes), '\0');
+  WideCharToMultiByte(
+      CP_UTF8, 0, buffer.c_str(), static_cast<int>(buffer.size()), utf8.data(), bytes, nullptr,
+      nullptr);
+  return utf8;
+#else
+  std::error_code code;
+  const std::filesystem::path resolved = std::filesystem::read_symlink("/proc/self/exe", code);
+  return code ? std::string{} : resolved.string();
+#endif
+}
+
+} // namespace
+
+std::string applicationResourcePath() {
+  const std::string executable = executablePath();
+  if (executable.empty()) {
+    return {};
+  }
+
+  std::error_code ignored;
+  const std::filesystem::path directory =
+      std::filesystem::weakly_canonical(std::filesystem::path(executable).parent_path(), ignored);
+
+  // `Foo.app/Contents/MacOS/basalt_appkit` -> `Foo.app/Contents/Resources`,
+  // which is where cli/packageApp.ts puts an app's files and where
+  // NSBundle.mainBundle.resourcePath would point. Recognised by the layout
+  // rather than by the platform, because a macOS host run straight out of a
+  // build directory is not in a bundle and should answer that directory.
+  if (directory.filename() == "MacOS" && directory.parent_path().filename() == "Contents") {
+    return (directory.parent_path() / "Resources").string();
+  }
+  return directory.string();
+}
+
+DesktopAppModule::DesktopAppModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+    : TurboModule(kModuleName, std::move(jsInvoker)) {
+  methodMap_["getResourcePath"] = MethodMetadata{0, getResourcePath};
+}
+
+facebook::jsi::Value DesktopAppModule::getResourcePath(
+    facebook::jsi::Runtime &runtime,
+    facebook::react::TurboModule & /*module*/,
+    const facebook::jsi::Value * /*args*/,
+    size_t /*count*/) {
+  return facebook::jsi::String::createFromUtf8(runtime, applicationResourcePath());
+}
+
+} // namespace basalt

package/native/core/AppPaths.h

@@ -0,0 +1,53 @@
+// Where the application's own files are.
+//
+// A packaged desktop application has somewhere its build put the things it
+// ships with -- a script it runs, a model it loads, a binary it drives -- and
+// where that is differs by desktop. This project's packager is what decides it:
+// `Foo.app/Contents/Resources` beside `Contents/MacOS/basalt_appkit` on macOS,
+// and beside the executable on Linux and Windows, where there is no separate
+// resources directory. See cli/packageApp.ts.
+//
+// So it is this platform's to answer, not the app's. An app working it out for
+// itself is an app that has to know the layout of a bundle it did not build --
+// which is exactly the knowledge that is supposed to live here, and which
+// changes the day the packager changes.
+//
+// Derived from the running executable rather than asked of a toolkit.
+// `NSBundle.mainBundle.resourcePath` is the authoritative answer on macOS and
+// there is no equivalent on the other two, so one portable derivation beats one
+// real answer and two approximations -- and the layout it derives from is this
+// project's own.
+
+#pragma once
+
+#include <FBReactNativeSpec/FBReactNativeSpecJSI.h>
+
+#include <memory>
+#include <string>
+
+namespace basalt {
+
+// The directory holding what the build put beside the application, or empty
+// when the running executable's path cannot be determined at all.
+//
+// A development run, where the host is started straight out of a build
+// directory, answers that directory: there is no bundle, and the honest answer
+// to "where are my resources" is "where the binary is".
+std::string applicationResourcePath();
+
+// `NativeModules.BasaltApp`, which is how JavaScript asks.
+class DesktopAppModule : public facebook::react::TurboModule {
+ public:
+  static constexpr auto kModuleName = "BasaltApp";
+
+  explicit DesktopAppModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+
+ private:
+  static facebook::jsi::Value getResourcePath(
+      facebook::jsi::Runtime &runtime,
+      facebook::react::TurboModule &module,
+      const facebook::jsi::Value *args,
+      size_t count);
+};
+
+} // namespace basalt