basalt-core 0.0.0-rc5

package/native/tests/test_window_limits.cpp

@@ -0,0 +1,123 @@
+// How big a window may be: the clamp, which is portable.
+//
+// Worth a unit test rather than only an end-to-end one, because the end-to-end
+// half cannot run everywhere. Enforcing a limit needs a window manager to
+// enforce it, and CI runs the Linux host under Xvfb, which has none -- so the
+// scenario there asserts what the platform *says* it does and stops. This is
+// the arithmetic underneath, and it runs on any machine.
+//
+// The clamp exists at all because the toolkits disagree. AppKit's `setFrame:`
+// clamps a programmatic resize down to the maximum and not up to the minimum,
+// so a window asked to be 300x200 under a minimum of 500x400 went to 300x200 --
+// smaller than anything a person dragging its corner could have made it.
+
+#include "TestHarness.h"
+
+#include "WindowControl.h"
+
+#include <sstream>
+
+namespace {
+
+// Back to no limits at all, which is the state every other test assumes.
+struct NoLimits {
+  ~NoLimits() {
+    basalt::setWindowMinimumSize(0, 0);
+    basalt::setWindowMaximumSize(0, 0);
+  }
+};
+
+TEST(limits_nothing_is_clamped_by_default) {
+  const NoLimits reset;
+  double width = 123.0;
+  double height = 45.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+  EXPECT_EQ(width, 123.0);
+  EXPECT_EQ(height, 45.0);
+}
+
+TEST(limits_a_minimum_raises_a_smaller_request) {
+  const NoLimits reset;
+  basalt::setWindowMinimumSize(500, 400);
+  double width = 300.0;
+  double height = 200.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+
+  // Only where the platform says it does this. A desktop that reports
+  // `minimumSize: false` must not quietly enforce one here: the whole value of
+  // answering the question is that the answer can be trusted.
+  if (basalt::windowCapabilities().minimumSize) {
+    EXPECT_EQ(width, 500.0);
+    EXPECT_EQ(height, 400.0);
+  } else {
+    EXPECT_EQ(width, 300.0);
+    EXPECT_EQ(height, 200.0);
+  }
+}
+
+TEST(limits_a_maximum_lowers_a_larger_request) {
+  const NoLimits reset;
+  basalt::setWindowMaximumSize(800, 600);
+  double width = 1400.0;
+  double height = 1100.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+
+  if (basalt::windowCapabilities().maximumSize) {
+    EXPECT_EQ(width, 800.0);
+    EXPECT_EQ(height, 600.0);
+  } else {
+    // GTK4 removed `gtk_window_set_geometry_hints` and Wayland has no protocol
+    // for a maximum, so Linux reports false and is left alone. Enforcing one
+    // for a programmatic resize and not for a dragged corner would be a limit
+    // that half exists.
+    EXPECT_EQ(width, 1400.0);
+    EXPECT_EQ(height, 1100.0);
+  }
+}
+
+TEST(limits_a_request_already_inside_them_is_untouched) {
+  const NoLimits reset;
+  basalt::setWindowMinimumSize(400, 300);
+  basalt::setWindowMaximumSize(1000, 800);
+  double width = 700.0;
+  double height = 500.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+  EXPECT_EQ(width, 700.0);
+  EXPECT_EQ(height, 500.0);
+}
+
+TEST(limits_zero_clears_one_rather_than_pinning_a_window_to_nothing) {
+  const NoLimits reset;
+  basalt::setWindowMinimumSize(500, 400);
+  basalt::setWindowMinimumSize(0, 0);
+  double width = 100.0;
+  double height = 80.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+  EXPECT_EQ(width, 100.0);
+  EXPECT_EQ(height, 80.0);
+}
+
+TEST(limits_a_negative_is_the_same_as_clearing) {
+  // An app clearing a constraint is more likely to pass 0 than -1, and neither
+  // should be a window that cannot be narrower than minus one pixel.
+  const NoLimits reset;
+  basalt::setWindowMinimumSize(-1, -1);
+  const basalt::WindowSizeLimits limits = basalt::windowSizeLimits();
+  EXPECT_EQ(limits.minWidth, 0.0);
+  EXPECT_EQ(limits.minHeight, 0.0);
+}
+
+TEST(limits_one_dimension_can_be_limited_without_the_other) {
+  const NoLimits reset;
+  basalt::setWindowMinimumSize(500, 0);
+  double width = 300.0;
+  double height = 10.0;
+  basalt::constrainToWindowSizeLimits(width, height);
+  if (basalt::windowCapabilities().minimumSize) {
+    EXPECT_EQ(width, 500.0);
+  }
+  // Never raised: a limit of zero is no limit, not a limit of zero.
+  EXPECT_EQ(height, 10.0);
+}
+
+} // namespace

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "basalt-core",
+  "version": "0.0.0-rc5",
+  "description": "React Native on the desktop, over React Native's own C++ core rather than a fork. The shared half: the platform module, the Metro configuration that resolves it, the bundler, and the C++ that is not about a toolkit.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vincentvella/basalt-core.git",
+    "directory": "packages/basalt-core"
+  },
+  "main": "dist/src/index.js",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./metro-config": "./dist/metro-config.js",
+    "./cli/bundleWithAssets": "./dist/cli/bundleWithAssets.js",
+    "./cli/desktop": "./dist/cli/desktop.js",
+    "./cli/metro": "./dist/cli/metro.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "native",
+    "metro-config.js",
+    "react-native.config.js",
+    "supported-versions.json"
+  ],
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.25.0"
+  },
+  "bin": {
+    "basalt": "dist/cli/basalt.js",
+    "basalt-bundle": "dist/cli/bundle-cli.js"
+  },
+  "types": "dist/src/index.d.ts",
+  "scripts": {
+    "build": "../../scripts/build_ts.sh",
+    "prepack": "../../scripts/build_ts.sh"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,86 @@
+/**
+ * What React Native's CLI reads out of this package.
+ *
+ * An entry per platform, without which the CLI does not believe these are
+ * platforms and `react-native bundle --platform macos` is rejected before Metro
+ * sees it.
+ *
+ * Commands are not here. `run-linux` needs a GTK host to run, so it belongs to
+ * basalt-gtk -- the CLI reads a react-native.config.js out of every
+ * dependency, so an app that has only the AppKit package never sees a command it
+ * could not have used.
+ *
+ * `projectConfig` returning null for a project with no native directory is how
+ * the CLI is told "this project does not target that platform", and is what
+ * keeps the command out of the way in an app that only builds for iOS. Today
+ * every project targets all three, because there is no per-project native code
+ * to look for yet; when there is, this is where the check goes.
+ *
+ * @format
+ */
+
+// Checked, not compiled.
+//
+// This file stays JavaScript on purpose, and it is the only one in the package
+// that does. React Native's CLI reads it from `node_modules/<package>/` by
+// path convention rather than through `exports`, so it has to be loadable as
+// CommonJS at exactly this path -- and what it exports is a data structure,
+// which is the one shape types buy nothing to write and everything to check.
+// `@ts-check` gives the checking without putting a tool this project does not
+// control behind a build step.
+// @ts-check
+'use strict';
+
+/** @typedef {{projectConfig: () => object, dependencyConfig: () => null}} PlatformEntry */
+
+// `./dist/metro-config`, not `./metro-config`: that file is TypeScript now and
+// this one is not compiled, so the sibling it used to sit beside is no longer
+// there. This is the file React Native's CLI loads from the package root, so
+// it must resolve with nothing but Node.
+// Required from `dist` at runtime, typed from the source.
+//
+// They are the same module. Splitting them this way is what stops checking
+// this file from depending on the output of the very compilation that checks
+// it -- `./dist/metro-config.d.ts` does not exist yet on a clean build, and a
+// config file that only type-checks on the second run is a trap.
+//
+// The path is built rather than written so that TypeScript does not try to
+// resolve it; the cast beside it says what it is.
+const metroConfig = /** @type {typeof import('./metro-config')} */ (
+  require(`${__dirname}/dist/metro-config`)
+);
+const DESKTOP_PLATFORMS = metroConfig.DESKTOP_PLATFORMS;
+
+// The same entry for each. They differ in their view layer and in nothing the
+// CLI can see, which is the whole argument of this project restated as four
+// lines of configuration.
+//
+// Deliberately no `npmPackageName`, which is the one field that looks obviously
+// right and is wrong here.
+//
+// Setting it tells the CLI this is an *out-of-tree platform* in the
+// react-native-macos and react-native-windows sense: a fork. It then installs
+// `reactNativePlatformResolver`, which rewrites every `react-native/...` import
+// to `basalt-core/...` when bundling, and requires this package to
+// export `./setup-env`. Both are correct for a fork that vendors React Native's
+// JavaScript. This package vendors none of it -- it redirects nine of React
+// Native's own shims to their existing `.android.js` siblings and overrides two
+// files -- so the rewrite sends every import into a package that does not
+// contain it.
+//
+// Without the field these are still platforms the CLI accepts, and resolution
+// stays with `withDesktopPlatforms` in metro-config.js, which is where the
+// actual policy lives.
+/** @type {Record<string, PlatformEntry>} */
+const platforms = {};
+for (const name of DESKTOP_PLATFORMS) {
+  platforms[name] = {
+    projectConfig: () => ({}),
+    // No autolinking: nothing here has native code to link yet, and claiming
+    // otherwise would make the CLI generate references to files that do not
+    // exist.
+    dependencyConfig: () => null,
+  };
+}
+
+module.exports = {platforms};

package/supported-versions.json

@@ -0,0 +1,66 @@
+{
+  "$comment": [
+    "Which React Native this platform supports, and which Hermes to build for it.",
+    "",
+    "A pinned triple: basalt-core, React Native, and Hermes are chosen and",
+    "tested together, the way react-native-windows pins its own Hermes NuGet",
+    "version and one exact React Native in peerDependencies. The alternative --",
+    "deriving Hermes from whatever React Native an app happens to have -- was tried",
+    "and abandoned: React Native 0.81's Hermes wants a jsi header newer React",
+    "Native does not ship and names its build target differently, so following the",
+    "app leads three compile errors deep into a version nobody claimed to support.",
+    "",
+    "Hermes is pinned here rather than read from React Native because this platform",
+    "builds it from source. Windows, macOS, iOS and Android all consume a prebuilt",
+    "Hermes; Meta publishes one for each of them and none for Linux. That single",
+    "difference is where every version problem here comes from.",
+    "",
+    "To add a version: add an entry, bootstrap against it, and run both suites.",
+    "Untested is not supported -- saying so is the point of this file."
+  ],
+  "supported": [
+    {
+      "reactNative": "0.86",
+      "hermes": "250829098.0.0-stable",
+      "hermesTarget": "hermesvm",
+      "verified": "0.86.3",
+      "notes": "The React Native a current Expo app installs, which is why it is supported.",
+      "limitations": [
+        "No Fast Refresh. ReactHost::destroyReactInstance sets reactInstanceData_->mountingManager to null on teardown, so a reload recreates the instance without a mounting manager and the host collapses. Reproduced, root-caused, and fixed upstream in 0.87 by deleting those three lines. Four of five end-to-end scenarios pass; the fifth is this."
+      ]
+    },
+    {
+      "reactNative": "0.87",
+      "hermes": "250829098.0.0-stable",
+      "verified": "0.87.1",
+      "notes": "60/60 unit and 5/5 end-to-end, macOS and CI. What CI pins.",
+      "hermesTarget": "hermesvm"
+    }
+  ],
+  "development": {
+    "reactNative": "1000.0.0",
+    "hermes": "250829098.0.0-stable",
+    "notes": "React Native main, which calls itself 1000.0.0. Where development happens; the weekly drift job tracks it.",
+    "hermesTarget": "hermesvm"
+  },
+  "known-unsupported": [
+    {
+      "reactNative": "0.83 - 0.85",
+      "why": "Never built or tested. Nothing suggests they would not work; nothing has checked."
+    },
+    {
+      "reactNative": "0.82 and older",
+      "why": "Attempted for 0.81.6 and stopped deliberately. Six differences, of which the last three are structural.",
+      "what-it-would-take": [
+        "~~RN$TurboInterop set before the bundle evaluates, or no native module resolves at all.~~ Done: core/TurboModuleProxy.h installs globalThis.__turboModuleProxy as an alias for nativeModuleProxy[name], so TurboModuleRegistry's first question succeeds and the gated fallback is never reached. Verified against 0.81's own JavaScript -- kino's unmodified bundle reaches Running \"main\" with no flag prepended.",
+        "Its Hermes builds `libhermes` rather than `hermesvm`, and React Native links `hermes-engine::libhermes`. Both handled already.",
+        "Its codegen has no -f flag, writes core artifacts inside the package, and exits non-zero after printing Done. Handled already.",
+        "Our own sources need version guards: TextAlignment has no Start or End, TextMeasureCacheKey has no pointScaleFactor, BaseTouch has no timeStamp. The first two are done.",
+        "GtkAnimationChoreographer has to be compiled out: there is no react/renderer/animationbackend, only react/renderer/animations.",
+        "ReactHost takes eleven parameters rather than twelve, takes TurboModuleManagerDelegates rather than TurboModuleProviders, and has no choreographer parameter. A second host construction path.",
+        "There is no websocket client. 0.81 ships IWebSocketClient with no implementation behind it, so no packager connection, no Fast Refresh, and no websockets for the app. Writing one is the largest piece."
+      ],
+      "verdict": "A permanent second code path through the host, for the version that would also be the most degraded. Three of the six are now handled, and the three that remain are the structural ones: ReactHost's constructor, the missing websocket client, and the choreographer. Worth doing only for a specific app that needs it, and kino would still stop at Expo afterwards."
+    }
+  ]
+}