basalt-core 0.0.0-rc5

package/native/tests/test_key_events.cpp

@@ -0,0 +1,235 @@
+// Which view claims which key. The decision, not the delivery.
+//
+// A host asks `handledBy` in the middle of `keyDown:`, `key-pressed` or
+// `WM_KEYDOWN` and consumes the key or passes it on by the answer. So the two
+// failures that matter are opposite and both silent: claiming a key nobody
+// declared swallows it from the menu and from text fields, and failing to claim
+// one that was declared means a shortcut that quietly never fires.
+
+#include "TestHarness.h"
+
+#include "KeyEvents.h"
+#include "TestKeys.h"
+
+#include <sstream>
+#include <string>
+#include <vector>
+
+using basalt::KeyCombination;
+using basalt::KeyModifiers;
+
+namespace {
+
+KeyCombination press(std::string key, KeyModifiers modifiers = {}) {
+  return KeyCombination{std::move(key), modifiers};
+}
+
+KeyModifiers meta() { return KeyModifiers{.alt = false, .ctrl = false, .meta = true, .shift = false}; }
+KeyModifiers metaShift() {
+  return KeyModifiers{.alt = false, .ctrl = false, .meta = true, .shift = true};
+}
+
+// Tags are React's and mean nothing here, so they are just distinct numbers.
+constexpr facebook::react::Tag kPane = 11;
+constexpr facebook::react::Tag kWindow = 3;
+constexpr facebook::react::Tag kUnrelated = 99;
+
+void reset() {
+  for (facebook::react::Tag tag : {kPane, kWindow, kUnrelated}) {
+    basalt::clearHandledKeys(tag);
+  }
+}
+
+} // namespace
+
+TEST(keys_a_view_that_claimed_nothing_claims_nothing) {
+  reset();
+  // The common case by a wide margin: no app in this repository's suite declares
+  // a key, and every one of them presses some.
+  EXPECT(!basalt::handlesKey(kPane, press("a")));
+  EXPECT(!basalt::handledBy({kPane, kWindow}, press("a")).has_value());
+  EXPECT_EQ((int)basalt::handledKeyViewCount(), 0);
+}
+
+TEST(keys_a_claim_matches_on_key_and_modifiers) {
+  reset();
+  basalt::setHandledKeys(kPane, {press("z", meta())});
+
+  EXPECT(basalt::handlesKey(kPane, press("z", meta())));
+  // Same key, no modifier: a different combination, and an app that bound Cmd+Z
+  // did not bind Z.
+  EXPECT(!basalt::handlesKey(kPane, press("z")));
+  // Same modifiers, different key.
+  EXPECT(!basalt::handlesKey(kPane, press("y", meta())));
+  // A modifier the claim did not ask for. Shift+Cmd+Z is redo and is its own
+  // binding; matching it here would fire undo.
+  EXPECT(!basalt::handlesKey(kPane, press("z", metaShift())));
+}
+
+TEST(keys_case_follows_the_character) {
+  reset();
+  // As in a browser: Shift+A reports "A" with shift set, and an app may bind
+  // either. They are different combinations and neither is wrong.
+  basalt::setHandledKeys(kPane, {press("A", KeyModifiers{.shift = true})});
+  EXPECT(basalt::handlesKey(kPane, press("A", KeyModifiers{.shift = true})));
+  EXPECT(!basalt::handlesKey(kPane, press("a", KeyModifiers{.shift = true})));
+}
+
+TEST(keys_the_innermost_claim_wins) {
+  reset();
+  // Both claim it. The path runs from the focused view outwards, so the pane
+  // answers -- a shortcut on a pane should beat the same one on the window.
+  basalt::setHandledKeys(kPane, {press(basalt::kKeyEscape)});
+  basalt::setHandledKeys(kWindow, {press(basalt::kKeyEscape)});
+
+  const auto handler = basalt::handledBy({kPane, kWindow}, press(basalt::kKeyEscape));
+  EXPECT(handler.has_value());
+  EXPECT_EQ((int)*handler, (int)kPane);
+
+  // And with the pane out of the path, the window answers: an ancestor's claim
+  // is not shadowed by a descendant that exists, only by one in the path.
+  const auto outer = basalt::handledBy({kWindow}, press(basalt::kKeyEscape));
+  EXPECT(outer.has_value());
+  EXPECT_EQ((int)*outer, (int)kWindow);
+}
+
+TEST(keys_a_view_outside_the_path_is_not_asked) {
+  reset();
+  // The focus path is the whole of it. A view elsewhere in the tree claiming a
+  // key must not swallow it -- that is how a background pane would steal typing.
+  basalt::setHandledKeys(kUnrelated, {press("j")});
+  EXPECT(!basalt::handledBy({kPane, kWindow}, press("j")).has_value());
+}
+
+TEST(keys_a_new_declaration_replaces_the_old) {
+  reset();
+  basalt::setHandledKeys(kPane, {press("j"), press("k"), press("l")});
+  EXPECT(basalt::handlesKey(kPane, press("k")));
+
+  // A re-render hands over the whole list. Merging would keep "k" alive after
+  // the app stopped declaring it, which would look like the shortcut working --
+  // the failure this list being assigned rather than appended exists to prevent.
+  basalt::setHandledKeys(kPane, {press("j"), press("l")});
+  EXPECT(basalt::handlesKey(kPane, press("j")));
+  EXPECT(!basalt::handlesKey(kPane, press("k")));
+  EXPECT_EQ((int)basalt::handledKeyViewCount(), 1);
+}
+
+TEST(keys_an_empty_declaration_is_not_the_same_as_unmounting) {
+  reset();
+  basalt::setHandledKeys(kPane, {press("j")});
+  basalt::setHandledKeys(kPane, {});
+  // Still registered, claiming nothing: a view whose shortcuts are all disabled
+  // exists and may get them back.
+  EXPECT_EQ((int)basalt::handledKeyViewCount(), 1);
+  EXPECT(!basalt::handlesKey(kPane, press("j")));
+
+  basalt::clearHandledKeys(kPane);
+  EXPECT_EQ((int)basalt::handledKeyViewCount(), 0);
+}
+
+TEST(keys_a_press_reaches_the_listener) {
+  reset();
+  basalt::setHandledKeys(kPane, {press("m")});
+
+  int calls = 0;
+  facebook::react::Tag seenTag = 0;
+  std::string seenKey;
+  bool seenShift = false;
+  basalt::setKeyListener([&](facebook::react::Tag tag, const KeyCombination &pressed) {
+    calls++;
+    seenTag = tag;
+    seenKey = pressed.key;
+    seenShift = pressed.modifiers.shift;
+  });
+
+  basalt::reportKey(kPane, press("m", KeyModifiers{.shift = true}));
+  EXPECT_EQ(calls, 1);
+  EXPECT_EQ((int)seenTag, (int)kPane);
+  EXPECT_EQ(seenKey, std::string("m"));
+  EXPECT(seenShift);
+
+  // Reported as given, not re-matched: the host has already decided, and a
+  // second opinion here could disagree with the one the key was consumed on.
+  basalt::reportKey(kPane, press("not-a-key"));
+  EXPECT_EQ(calls, 2);
+
+  basalt::setKeyListener(nullptr);
+  basalt::reportKey(kPane, press("m"));
+  EXPECT_EQ(calls, 2);
+}
+
+TEST(keys_the_special_names_are_the_ones_a_browser_uses) {
+  // Spelled once, here, because three hosts mapping their own key codes is three
+  // chances to write "Arrowleft" -- and the failure is a shortcut that silently
+  // never fires, on one platform only. core/TestQuitFile.h has the same note for
+  // the same reason.
+  EXPECT_EQ(std::string(basalt::kKeyArrowLeft), std::string("ArrowLeft"));
+  EXPECT_EQ(std::string(basalt::kKeyArrowRight), std::string("ArrowRight"));
+  EXPECT_EQ(std::string(basalt::kKeyArrowUp), std::string("ArrowUp"));
+  EXPECT_EQ(std::string(basalt::kKeyArrowDown), std::string("ArrowDown"));
+  EXPECT_EQ(std::string(basalt::kKeyEscape), std::string("Escape"));
+  EXPECT_EQ(std::string(basalt::kKeyEnter), std::string("Enter"));
+  EXPECT_EQ(std::string(basalt::kKeyTab), std::string("Tab"));
+  EXPECT_EQ(std::string(basalt::kKeyPageUp), std::string("PageUp"));
+  EXPECT_EQ(std::string(basalt::kKeyPageDown), std::string("PageDown"));
+  // The one that looks like a mistake and is not: a space is a character.
+  EXPECT_EQ(std::string(basalt::kKeySpace), std::string(" "));
+}
+
+
+// --- BASALT_TEST_KEY's syntax ----------------------------------------------
+//
+// Parsed in core rather than in three hosts, because three parsers is three
+// chances to disagree about what "z+meta" means -- and to disagree quietly: the
+// wrong answer is a combination that matches nothing, which a scenario reports as
+// a shortcut that did not fire rather than as a bad instrument.
+
+TEST(keys_the_instrument_reads_a_bare_key) {
+  const KeyCombination pressed = basalt::parseKeyPress("m");
+  EXPECT_EQ(pressed.key, std::string("m"));
+  EXPECT(pressed.modifiers == KeyModifiers{});
+}
+
+TEST(keys_the_instrument_reads_modifiers) {
+  const KeyCombination undo = basalt::parseKeyPress("z+meta");
+  EXPECT_EQ(undo.key, std::string("z"));
+  EXPECT(undo.modifiers.meta);
+  EXPECT(!undo.modifiers.shift);
+
+  const KeyCombination redo = basalt::parseKeyPress("z+meta+shift");
+  EXPECT(redo.modifiers.meta);
+  EXPECT(redo.modifiers.shift);
+  // The pair that must differ, or a test for redo would pass on undo.
+  EXPECT(!(undo == redo));
+}
+
+TEST(keys_the_instrument_reads_a_named_key) {
+  EXPECT_EQ(basalt::parseKeyPress("ArrowLeft").key, std::string("ArrowLeft"));
+  // A space is a key named " ", and writing it in an environment variable means
+  // the parser must not trim.
+  EXPECT_EQ(basalt::parseKeyPress(" ").key, std::string(" "));
+}
+
+TEST(keys_the_instrument_reads_a_literal_plus) {
+  // "+" is both the separator and a key an editor binds -- zoom in. Spelt by
+  // being first, which is the one case where an empty piece means something.
+  EXPECT_EQ(basalt::parseKeyPress("+").key, std::string("+"));
+  const KeyCombination zoom = basalt::parseKeyPress("++meta");
+  EXPECT_EQ(zoom.key, std::string("+"));
+  EXPECT(zoom.modifiers.meta);
+}
+
+TEST(keys_the_instrument_ignores_a_modifier_it_does_not_know) {
+  // A typo gives a combination that matches nothing rather than an error, and the
+  // scenario then reports a shortcut that did not fire -- the honest symptom.
+  const KeyCombination pressed = basalt::parseKeyPress("z+command");
+  EXPECT_EQ(pressed.key, std::string("z"));
+  EXPECT(pressed.modifiers == KeyModifiers{});
+}
+
+TEST(keys_the_instrument_is_empty_when_unset) {
+  // Every scenario that does not press a key relies on this, which is all but
+  // one of them.
+  EXPECT(basalt::scriptedKeyPresses().empty());
+}

package/native/tests/test_momentum.cpp

@@ -0,0 +1,138 @@
+// Tests for the fling model.
+//
+// Core's, so compiled into every platform's suite -- although only one platform
+// uses it. macOS decelerates a scroll itself and the AppKit host only reports
+// what the system sends; GTK emits one velocity and stops, so the coasting is
+// this project's. See core/ScrollMomentum.h.
+//
+// Testable at all because the model is a pure function of a velocity and a
+// clock: no widget, no frame clock, and no waiting a second for a fling to
+// finish.
+
+#include "TestHarness.h"
+
+#include "ScrollMomentum.h"
+
+#include <sstream>
+
+namespace {
+
+using basalt::ScrollMomentum;
+
+// A frame at sixty a second, which is what a tick callback hands over.
+constexpr double kFrame = 1.0 / 60.0;
+
+// How far a fling travels in total, and how many frames it takes. Bounded, so
+// a model that never stops fails the assertion rather than hanging the suite.
+struct Flight {
+  double distanceY{0};
+  int frames{0};
+};
+
+Flight flyY(ScrollMomentum &momentum) {
+  Flight flight;
+  double dx = 0;
+  double dy = 0;
+  while (momentum.advance(kFrame, dx, dy) && flight.frames < 6000) {
+    flight.distanceY += dy;
+    flight.frames++;
+  }
+  flight.distanceY += dy;
+  flight.frames++;
+  return flight;
+}
+
+} // namespace
+
+TEST(momentum_a_fling_travels_and_stops) {
+  ScrollMomentum momentum;
+  EXPECT(momentum.start(0, 1200, ScrollMomentum::kNormalDeceleration));
+  EXPECT(momentum.isRunning());
+
+  const Flight flight = flyY(momentum);
+  EXPECT(!momentum.isRunning());
+  // The numbers are the model's, not a target: 1200px/s at 0.998 per
+  // millisecond comes out at about 595 pixels over about 111 frames, which is
+  // roughly what the same flick does on a phone. Asserted as a range, so a
+  // change in the constants is caught and a change in the integration step is
+  // not.
+  EXPECT(flight.distanceY > 450);
+  EXPECT(flight.distanceY < 750);
+  EXPECT(flight.frames > 60);
+  EXPECT(flight.frames < 200);
+}
+
+TEST(momentum_a_faster_deceleration_travels_less) {
+  ScrollMomentum normal;
+  normal.start(0, 1200, ScrollMomentum::kNormalDeceleration);
+  const Flight slow = flyY(normal);
+
+  ScrollMomentum fast;
+  fast.start(0, 1200, ScrollMomentum::kFastDeceleration);
+  const Flight quick = flyY(fast);
+
+  // What React Native's `decelerationRate` prop is for. 'fast' is the smaller
+  // number and the shorter fling, which reads backwards until you remember it
+  // is the fraction of the velocity that survives each millisecond.
+  EXPECT(quick.distanceY < slow.distanceY);
+  EXPECT(quick.frames < slow.frames);
+}
+
+TEST(momentum_a_fling_keeps_its_direction_on_both_axes) {
+  ScrollMomentum momentum;
+  momentum.start(-800, 1600, ScrollMomentum::kNormalDeceleration);
+  double dx = 0;
+  double dy = 0;
+  momentum.advance(kFrame, dx, dy);
+  EXPECT(dx < 0);
+  EXPECT(dy > 0);
+  // And in proportion: the model decays a velocity, it does not reshape one.
+  EXPECT_NEAR(dy / dx, -2.0, 0.001);
+}
+
+TEST(momentum_a_slow_flick_is_not_a_fling) {
+  ScrollMomentum momentum;
+  // Below the stopping speed, so it would report a momentum scroll that began
+  // and ended with nothing in between -- worse than not reporting one.
+  EXPECT(!momentum.start(0, 5, ScrollMomentum::kNormalDeceleration));
+  EXPECT(!momentum.isRunning());
+  double dx = 0;
+  double dy = 0;
+  EXPECT(!momentum.advance(kFrame, dx, dy));
+  EXPECT_NEAR(dx, 0.0, 0.0001);
+  EXPECT_NEAR(dy, 0.0, 0.0001);
+}
+
+TEST(momentum_stopping_ends_it_at_once) {
+  ScrollMomentum momentum;
+  momentum.start(0, 2000, ScrollMomentum::kNormalDeceleration);
+  momentum.stop();
+  EXPECT(!momentum.isRunning());
+  double dx = 0;
+  double dy = 0;
+  EXPECT(!momentum.advance(kFrame, dx, dy));
+  EXPECT_NEAR(dy, 0.0, 0.0001);
+}
+
+TEST(momentum_a_stalled_frame_clock_does_not_teleport_the_list) {
+  ScrollMomentum momentum;
+  momentum.start(0, 1000, ScrollMomentum::kNormalDeceleration);
+  double dx = 0;
+  double dy = 0;
+  // A whole second between frames -- a window dragged between monitors, or a
+  // machine that swapped. Without a clamp this is a thousand pixels in one
+  // step, which reads as the list jumping rather than coasting.
+  momentum.advance(1.0, dx, dy);
+  EXPECT(dy <= 100.0);
+}
+
+TEST(momentum_a_deceleration_rate_of_one_would_never_stop) {
+  ScrollMomentum momentum;
+  // `decelerationRate` is a float prop an app can set to anything. A rate of 1
+  // keeps the whole velocity every millisecond, which is a list that scrolls
+  // for ever; the model clamps rather than trusting it.
+  momentum.start(0, 1000, 1.0);
+  const Flight flight = flyY(momentum);
+  EXPECT(flight.frames < 6000);
+  EXPECT(!momentum.isRunning());
+}

package/native/tests/test_quit_file.cpp

@@ -0,0 +1,104 @@
+// The instrument that lets the harness end a run at a moment of its choosing.
+//
+// What is testable here is the decision -- is the variable set, and is the file
+// there yet -- rather than the quitting, which is three different shutdowns and
+// belongs to each host. This runs on all three, which is the point: the
+// instrument exists because the *portable* way to end a host was a signal, and
+// Windows has no SIGTERM.
+
+#include "TestHarness.h"
+
+#include "TestQuitFile.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+#include <string>
+
+namespace {
+
+// A path that does not exist yet, in the place the platform keeps such things.
+std::string scratchPath() {
+  std::error_code ignored;
+  const std::filesystem::path path =
+      std::filesystem::temp_directory_path(ignored) / "basalt-test-quit-file-probe";
+  return path.string();
+}
+
+void setVariable(const std::string &value) {
+#ifdef _WIN32
+  _putenv_s(basalt::kTestQuitFileVar, value.c_str());
+#else
+  setenv(basalt::kTestQuitFileVar, value.c_str(), 1);
+#endif
+}
+
+} // namespace
+
+// Set before anything reads it, because the path is cached on first read -- the
+// environment does not change under a running process, and each host asks for
+// this on a timer. One test therefore establishes it for the file, which is why
+// the ordering below is deliberate rather than incidental.
+TEST(quit_file_reads_the_variable) {
+  const std::string path = scratchPath();
+  std::error_code ignored;
+  std::filesystem::remove(path, ignored);
+  setVariable(path);
+
+  EXPECT(basalt::testQuitFilePath().has_value());
+  EXPECT_EQ(*basalt::testQuitFilePath(), path);
+}
+
+TEST(quit_file_is_not_there_until_it_is) {
+  const std::string path = *basalt::testQuitFilePath();
+  std::error_code ignored;
+  std::filesystem::remove(path, ignored);
+
+  // The whole contract: false until the file exists, and true once it does.
+  // A host polls this, so the transition is the instrument.
+  EXPECT(!basalt::testQuitFileAppeared());
+
+  { std::ofstream created(path); }
+  EXPECT(basalt::testQuitFileAppeared());
+
+  // And not cached, unlike the path: a stale true would quit the next run at
+  // startup, before it had done anything, and the failure would look like a
+  // crash rather than like a leftover file.
+  std::filesystem::remove(path, ignored);
+  EXPECT(!basalt::testQuitFileAppeared());
+}
+
+TEST(quit_file_is_content_free) {
+  const std::string path = *basalt::testQuitFilePath();
+  std::error_code ignored;
+
+  // Existence is the message. An empty file is the normal case, because the
+  // harness has nothing to say beyond "now" -- and if content mattered there
+  // would be a race between creating the file and writing it.
+  { std::ofstream created(path); }
+  EXPECT(basalt::testQuitFileAppeared());
+
+  { std::ofstream created(path); created << "ignored"; }
+  EXPECT(basalt::testQuitFileAppeared());
+
+  // A directory at that path counts too. Nothing creates one, and reporting it
+  // as "not yet" would hang the run instead of ending it.
+  std::filesystem::remove(path, ignored);
+  std::filesystem::create_directory(path, ignored);
+  EXPECT(basalt::testQuitFileAppeared());
+  std::filesystem::remove(path, ignored);
+}
+
+TEST(quit_file_poll_and_message_are_shared) {
+  // The three hosts read these rather than spelling them out, so that a person
+  // reading three transcripts side by side sees the same shutdown in each.
+  // BASALT_QUIT_AFTER_MS had to have its line retrofitted onto Windows after a
+  // scenario asserted on a string only two hosts printed.
+  EXPECT_EQ(std::string(basalt::kTestQuitFileVar), std::string("BASALT_TEST_QUIT_FILE"));
+  EXPECT_EQ(std::string(basalt::kTestQuitFileMessage),
+            std::string("BASALT_TEST_QUIT_FILE appeared; quitting"));
+  // Responsive enough not to show next to process teardown, and not a busy loop.
+  EXPECT(basalt::kTestQuitFilePollMs > 0 && basalt::kTestQuitFilePollMs <= 500);
+}

package/native/tests/test_scroll_animation.cpp

@@ -0,0 +1,120 @@
+// An animated scroll, which is arithmetic and so can be tested without a
+// display -- unlike almost everything else about a scroll view on these hosts.
+
+#include "TestHarness.h"
+
+#include "ScrollAnimation.h"
+
+#include <cmath>
+#include <sstream>
+
+using basalt::ScrollAnimation;
+
+namespace {
+
+TEST(scroll_animation_a_target_equal_to_the_start_is_not_an_animation) {
+  // So a caller can apply the offset and be done rather than running a curve
+  // that goes nowhere -- and, more to the point, never reporting that it
+  // finished.
+  ScrollAnimation animation;
+  EXPECT(!animation.start(10, 20, 10, 20));
+  EXPECT(!animation.isRunning());
+}
+
+TEST(scroll_animation_arrives_exactly_at_its_target) {
+  // Evaluated at the end rather than approached. An app that scrolls to a
+  // computed offset and reads it back should get its own number, not one a
+  // curve came close to.
+  ScrollAnimation animation;
+  EXPECT(animation.start(0, 0, 100, 250));
+
+  double x = 0;
+  double y = 0;
+  while (animation.advance(1.0 / 60.0, x, y)) {
+  }
+  EXPECT_EQ(x, 100.0);
+  EXPECT_EQ(y, 250.0);
+  EXPECT(!animation.isRunning());
+}
+
+TEST(scroll_animation_moves_monotonically_towards_the_target) {
+  ScrollAnimation animation;
+  animation.start(0, 0, 0, 300);
+
+  double x = 0;
+  double y = 0;
+  double previous = -1;
+  int steps = 0;
+  while (animation.advance(1.0 / 60.0, x, y)) {
+    EXPECT(y >= previous);
+    previous = y;
+    steps++;
+  }
+  // Something between "instant" and "a second". At 60Hz a 0.3s curve is about
+  // eighteen frames, and asserting the shape rather than the number keeps this
+  // from failing if the duration is tuned.
+  EXPECT(steps > 5);
+  EXPECT(steps < 60);
+}
+
+TEST(scroll_animation_starts_and_ends_slowly) {
+  // The property the curve was chosen for: zero derivative at both ends, so two
+  // scrolls in a row have no visible seam. Asserted as "the first step is
+  // smaller than a middle step", which is what that means in practice.
+  ScrollAnimation animation;
+  animation.start(0, 0, 0, 1000);
+
+  double x = 0;
+  double y = 0;
+  const double step = ScrollAnimation::kDurationSeconds / 10.0;
+
+  animation.advance(step, x, y);
+  const double first = y;
+
+  double previous = y;
+  for (int i = 0; i < 4; i++) {
+    animation.advance(step, x, y);
+  }
+  const double middle = y - previous;
+
+  EXPECT(first < middle);
+}
+
+TEST(scroll_animation_a_stopped_animation_reports_nothing_further) {
+  ScrollAnimation animation;
+  animation.start(0, 0, 0, 500);
+  double x = 0;
+  double y = 0;
+  animation.advance(0.05, x, y);
+  animation.stop();
+  EXPECT(!animation.isRunning());
+  EXPECT(!animation.advance(0.05, x, y));
+}
+
+TEST(scroll_animation_a_long_frame_does_not_overshoot) {
+  // A stalled frame -- a garbage collection, a slow mount -- hands this more
+  // time than the whole animation. It has to land on the target rather than
+  // past it, because an offset beyond the content is a scroll view showing
+  // nothing.
+  ScrollAnimation animation;
+  animation.start(0, 0, 0, 400);
+  double x = 0;
+  double y = 0;
+  EXPECT(!animation.advance(5.0, x, y));
+  EXPECT_EQ(y, 400.0);
+}
+
+TEST(scroll_animation_runs_backwards_as_well) {
+  ScrollAnimation animation;
+  animation.start(0, 900, 0, 0);
+  double x = 0;
+  double y = 900;
+  double previous = 901;
+  while (animation.advance(1.0 / 60.0, x, y)) {
+    EXPECT(y <= previous);
+    previous = y;
+  }
+  EXPECT_EQ(y, 0.0);
+}
+
+} // namespace

package/native/tests/test_scroll_bounds.cpp

@@ -0,0 +1,66 @@
+// The scrollable range, and what `contentInset` does to it.
+//
+// The arithmetic is four lines and was duplicated in three hosts, none of which
+// read the insets. These are the cases that tell the old behaviour from the new
+// one -- and the first three are the old behaviour, which must not move.
+
+#include "TestHarness.h"
+
+#include "ScrollBounds.h"
+
+// EXPECT_NEAR builds its message with a stream; the harness's header does not
+// pull one in, so each suite brings its own.
+#include <sstream>
+
+using basalt::clampScrollOffset;
+using basalt::ScrollAxisInsets;
+using basalt::scrollRangeFor;
+
+TEST(bounds_without_insets_are_what_they_always_were) {
+  const auto range = scrollRangeFor(100.0, 400.0);
+  EXPECT_NEAR(range.minimum, 0.0, 0.001);
+  EXPECT_NEAR(range.maximum, 300.0, 0.001);
+}
+
+TEST(bounds_content_that_fits_cannot_scroll) {
+  const auto range = scrollRangeFor(400.0, 100.0);
+  EXPECT_NEAR(range.minimum, 0.0, 0.001);
+  EXPECT_NEAR(range.maximum, 0.0, 0.001);
+}
+
+TEST(bounds_clamp_holds_an_offset_inside) {
+  EXPECT_NEAR(clampScrollOffset(-50.0, 100.0, 400.0), 0.0, 0.001);
+  EXPECT_NEAR(clampScrollOffset(999.0, 100.0, 400.0), 300.0, 0.001);
+  EXPECT_NEAR(clampScrollOffset(120.0, 100.0, 400.0), 120.0, 0.001);
+}
+
+TEST(bounds_a_leading_inset_allows_pulling_before_the_content) {
+  const auto range = scrollRangeFor(100.0, 400.0, ScrollAxisInsets{50.0, 0.0});
+  EXPECT_NEAR(range.minimum, -50.0, 0.001);
+  // The far end is unchanged: a top inset does not add room at the bottom.
+  EXPECT_NEAR(range.maximum, 300.0, 0.001);
+  EXPECT_NEAR(clampScrollOffset(-50.0, 100.0, 400.0, ScrollAxisInsets{50.0, 0.0}), -50.0, 0.001);
+  EXPECT_NEAR(clampScrollOffset(-80.0, 100.0, 400.0, ScrollAxisInsets{50.0, 0.0}), -50.0, 0.001);
+}
+
+TEST(bounds_a_trailing_inset_adds_room_at_the_far_end) {
+  const auto range = scrollRangeFor(100.0, 400.0, ScrollAxisInsets{0.0, 40.0});
+  EXPECT_NEAR(range.minimum, 0.0, 0.001);
+  EXPECT_NEAR(range.maximum, 340.0, 0.001);
+}
+
+// Content shorter than its container, with a leading inset: there is somewhere
+// to pull to and nowhere to scroll to, and the two ends must not cross.
+TEST(bounds_an_inset_on_content_that_fits_does_not_invert_the_range) {
+  const auto range = scrollRangeFor(400.0, 100.0, ScrollAxisInsets{50.0, 0.0});
+  EXPECT_NEAR(range.minimum, -50.0, 0.001);
+  EXPECT_NEAR(range.maximum, -50.0, 0.001);
+  EXPECT_NEAR(clampScrollOffset(10.0, 400.0, 100.0, ScrollAxisInsets{50.0, 0.0}), -50.0, 0.001);
+}
+
+TEST(bounds_both_insets_extend_both_ends) {
+  const auto range = scrollRangeFor(100.0, 400.0, ScrollAxisInsets{20.0, 30.0});
+  EXPECT_NEAR(range.minimum, -20.0, 0.001);
+  EXPECT_NEAR(range.maximum, 330.0, 0.001);
+  EXPECT_NEAR(range.length(), 350.0, 0.001);
+}