basalt-win32 0.2.1 → 0.2.2

package/native/CMakeLists.txt

@@ -96,6 +96,10 @@ get_property(BASALT_PACKAGE_WIN32_LINK_LIBRARIES GLOBAL PROPERTY BASALT_PACKAGE_
 # with a platform half has nowhere else to be tested: it is compiled into the
 # host binary, so the host's suite is the only binary that has it.
 get_property(BASALT_PACKAGE_TESTS GLOBAL PROPERTY BASALT_PACKAGE_TESTS)
+# And the ones only this host can compile, for the reason the AppKit package
+# gives: BASALT_PACKAGE_TESTS goes to all three suites, and a capability whose
+# platform half links prebuilt Skia has tests the other two cannot build.
+get_property(BASALT_PACKAGE_WIN32_TESTS GLOBAL PROPERTY BASALT_PACKAGE_WIN32_TESTS)
 
 if(NOT WIN32)
   # Not an error. A checkout builds every package it finds, and on anything but
@@ -165,7 +169,12 @@ add_library(basalt_win32_view STATIC
   # Where a hidden title bar's pieces are -- the caption buttons and the drag
   # regions. Pure geometry over the view tree, so it is tested here with no
   # window and no React Native.
-  win32/Win32TitleBarLayout.cpp)
+  win32/Win32TitleBarLayout.cpp
+  # Which pixels of a child-window peer are still the peer's: a <TextInput>'s
+  # EDIT clipped to its scrolled ancestors and cut away where the tree paints
+  # over it. Geometry over the view tree for the same reason, and tested the
+  # same way.
+  win32/Win32PeerClip.cpp)
 target_compile_options(basalt_win32_view PRIVATE ${BASALT_WIN32_WARNINGS})
 target_include_directories(basalt_win32_view PUBLIC win32)
 # The header-only part of core, and only that: FocusRing.h, Backface.h,
@@ -213,7 +222,10 @@ set(BASALT_WIN32_TEST_SOURCES
   # compares; this is where the platform half is checked.
   tests/test_win32_accessibility.cpp
   # A hidden title bar's geometry: the caption buttons and the drag regions.
-  tests/test_win32_titlebar.cpp)
+  tests/test_win32_titlebar.cpp
+  # A child-window peer's visible region: clipping and occlusion, which no
+  # other host needs because no other host has a widget it cannot order.
+  tests/test_win32_peer_clip.cpp)
 
 # ---------------------------------------------------------------------------
 # basalt_win32_mounting — the Windows half of the Fabric mounting manager.
@@ -266,6 +278,16 @@ if(TARGET basalt_core)
     # ...and of core/PlatformServices.h, which is also where postToUiThread
     # lives -- the marshalling the mounting manager depends on.
     win32/PlatformServicesWin32.cpp
+    # Waiting, over that same marshalling rather than over SetTimer. The
+    # header says why there is a second way to wait on a platform that has
+    # one: WM_TIMER ranks below WM_PAINT and so does not arrive in an app that
+    # paints continuously.
+    win32/Win32UiTimer.cpp
+    # The message loop, which is this host furniture rather than the mounting
+    # manager's -- and is here rather than beside main_win32.cpp so the suite
+    # can link it. What it has to get right is subtle enough to be worth a
+    # test; see win32/Win32RunLoopObserver.h.
+    win32/Win32RunLoopObserver.cpp
     # The window's title bar: DWM's colours and dark mode, and the caption the
     # host draws when an app hides the system's. And BasaltWindow, the module
     # JavaScript reaches it through.
@@ -302,10 +324,22 @@ if(TARGET basalt_core)
       # AppKitSkiaPeer.mm's opposite number. Where that one hands the package a
       # Metal layer, this renders into memory and lets the Direct2D walk draw
       # the result -- this host has no layer tree to hang a canvas in.
-      win32/Win32SkiaPeer.cpp
-      # The unicode factory the package asks for by name on anything that is
-      # not Apple, answered with the backend that is actually linked here.
-      win32/Win32SkiaUnicode.cpp)
+      win32/Win32SkiaPeer.cpp)
+  endif()
+
+  # The unicode factory the package asks for by name on anything that is not
+  # Apple, answered with the backend that is actually linked here.
+  #
+  # Outside the 2.x block because both generations need it and for the same
+  # reason: JsiSkParagraphBuilder takes SkUnicodes::ICU::Make() off Apple, and
+  # the Skia this platform builds for Windows carries libgrapheme rather than
+  # ICU in either generation. Inside it, a 3.x build -- which makes no
+  # skia_core -- linked everything else and then failed on one symbol.
+  get_property(BASALT_WIN32_PACKAGE_DEFINITIONS
+               GLOBAL PROPERTY BASALT_PACKAGE_DEFINITIONS)
+  if(TARGET skia_core OR
+     "BASALT_HAS_SKIA_GRAPHITE=1" IN_LIST BASALT_WIN32_PACKAGE_DEFINITIONS)
+    target_sources(basalt_win32_mounting PRIVATE win32/Win32SkiaUnicode.cpp)
   endif()
   # shell32 for ShellExecute; comctl32 for SetWindowSubclass, which is how a
   # <TextInput>'s EDIT peer is subclassed without breaking anything else that
@@ -322,9 +356,6 @@ if(TARGET basalt_core)
   # -------------------------------------------------------------------------
   add_executable(basalt_win32
     win32/main_win32.cpp
-    # The event beat. Not an observer on Windows: there is no "about to wait"
-    # hook, so the message loop itself is here. See the header.
-    win32/Win32RunLoopObserver.cpp
     win32/Win32AnimationChoreographer.cpp)
   target_compile_options(basalt_win32 PRIVATE ${BASALT_WIN32_WARNINGS})
   target_link_libraries(basalt_win32 PRIVATE basalt_win32_mounting)
@@ -339,6 +370,16 @@ if(TARGET basalt_core)
   add_executable(mount_harness_win32 win32/mount_harness_win32.cpp)
   target_compile_options(mount_harness_win32 PRIVATE ${BASALT_WIN32_WARNINGS})
   target_link_libraries(mount_harness_win32 PRIVATE basalt_win32_mounting)
+  # The same package libraries the host and the suite take, and for a reason
+  # that only showed up once a capability contributed something the mounting
+  # manager calls: a static library hands over the objects somebody references,
+  # so basalt-skia's module sat unreferenced here for as long as nothing but
+  # the TurboModule registry asked for it. The 3.x canvas is called straight
+  # from updateView, so the harness pulls it in and needs what it links.
+  if(BASALT_PACKAGE_WIN32_LINK_LIBRARIES)
+    target_link_libraries(mount_harness_win32
+                          PRIVATE ${BASALT_PACKAGE_WIN32_LINK_LIBRARIES})
+  endif()
 
   list(APPEND BASALT_WIN32_TEST_SOURCES
     ${BASALT_CORE_TESTS}
@@ -363,6 +404,7 @@ if(TARGET basalt_core)
     win32/Win32KeyEvents.cpp
     # A package's own tests; see the AppKit package for why they sit with core's.
     ${BASALT_PACKAGE_TESTS}
+    ${BASALT_PACKAGE_WIN32_TESTS}
     # Deliberately the same nine questions tests/test_mounting.cpp asks of GTK
     # and tests/test_appkit_mounting.mm asks of AppKit, in the same order with
     # the same tags. Most of what they test is whether the sharing still holds.
@@ -382,6 +424,11 @@ if(TARGET basalt_core)
     # innermost-first routing and the commands.
     tests/test_win32_focus.cpp
     tests/test_win32_scrollview.cpp
+    # Waiting, and the one condition that made the platform's own way of
+    # waiting stop working. See win32/Win32UiTimer.h.
+    tests/test_win32_ui_timer.cpp
+    # The message loop, and the bound on its drain.
+    tests/test_win32_run_loop.cpp
     # <TextInput>. The only tests here that make a window, because a text
     # field's peer is one -- see the file.
     tests/test_win32_textinput.cpp

package/native/tests/test_win32_input.cpp

@@ -25,6 +25,7 @@
 #include <react/renderer/components/view/ViewProps.h>
 
 #include <cstdint>
+#include <cstring>
 #include <string>
 #include <vector>
 
@@ -395,6 +396,46 @@ TEST(win32_a_synthesised_hover_walks_the_tree_without_an_emitter) {
 // hit-test suite covers it. `auto` and `url` reach a host as no keyword at all.
 // ---------------------------------------------------------------------------
 
+// A cursor as pixels, for comparing two of them.
+//
+// DrawIconEx at a size we choose rather than the cursor's own, so that a
+// 32-pixel drawn cursor and whatever size the system hands back are the same
+// shape of answer. False when the cursor cannot be drawn at all, which the
+// caller treats as "nothing to compare" rather than as a failure.
+bool cursorPixels(HCURSOR cursor, std::vector<std::uint8_t> &out) {
+  constexpr int kSide = 32;
+  HDC screen = GetDC(nullptr);
+  HDC dc = CreateCompatibleDC(screen);
+  BITMAPINFO info{};
+  info.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
+  info.bmiHeader.biWidth = kSide;
+  info.bmiHeader.biHeight = -kSide;
+  info.bmiHeader.biPlanes = 1;
+  info.bmiHeader.biBitCount = 32;
+  info.bmiHeader.biCompression = BI_RGB;
+  void *bits = nullptr;
+  HBITMAP bitmap = CreateDIBSection(dc, &info, DIB_RGB_COLORS, &bits, nullptr, 0);
+  bool ok = false;
+  if (bitmap != nullptr && bits != nullptr) {
+    HGDIOBJ previous = SelectObject(dc, bitmap);
+    // Cleared first: a DIB section is not promised zeroed, and comparing two
+    // cursors over two different piles of leftover memory would never match.
+    std::memset(bits, 0, static_cast<std::size_t>(kSide) * kSide * 4);
+    ok = DrawIconEx(dc, 0, 0, cursor, kSide, kSide, 0, nullptr, DI_NORMAL) != FALSE;
+    if (ok) {
+      out.assign(static_cast<std::uint8_t *>(bits),
+                 static_cast<std::uint8_t *>(bits) + static_cast<std::size_t>(kSide) * kSide * 4);
+    }
+    SelectObject(dc, previous);
+  }
+  if (bitmap != nullptr) {
+    DeleteObject(bitmap);
+  }
+  DeleteDC(dc);
+  ReleaseDC(nullptr, screen);
+  return ok;
+}
+
 TEST(win32_every_cursor_keyword_resolves_to_a_cursor_of_its_own) {
   // CSS's list, grouped into the families that may legitimately share one
   // cursor. A family is the exception the claim allows; everything else has to
@@ -490,6 +531,47 @@ TEST(win32_every_cursor_keyword_resolves_to_a_cursor_of_its_own) {
   }
   EXPECT_EQ(collided, std::string(""));
 
+  // And again by what they look like, which is not the same question.
+  //
+  // The check above compares handles, and two handles are different the
+  // moment they come from different calls -- `LoadCursorFromFileW` on a .cur
+  // and `LoadCursorW(IDC_HAND)` are two handles to the same drawing. That is
+  // exactly how `alias` and `pointer` came to be the same cursor without this
+  // test noticing: `alias` was loaded from %SystemRoot%\Cursors\aero_link.cur,
+  // which on Windows 11 is "Link Select" -- the hand IDC_HAND already gives
+  // `pointer`. Distinct handles, one picture, and the user cannot tell the two
+  // keywords apart.
+  //
+  // So this draws each one and compares the pixels. Thirty-two by thirty-two
+  // because that is the size DrawIconEx is being asked for rather than the
+  // size the cursor happens to be, which makes a system cursor and a drawn
+  // one comparable at all.
+  std::string looksTheSame;
+  for (const Resolved &left : resolved) {
+    for (const Resolved &right : resolved) {
+      if (left.family >= right.family) {
+        continue;
+      }
+      if (left.answer.cursor == nullptr || right.answer.cursor == nullptr) {
+        continue;
+      }
+      std::vector<std::uint8_t> leftBits;
+      std::vector<std::uint8_t> rightBits;
+      if (!cursorPixels(left.answer.cursor, leftBits) ||
+          !cursorPixels(right.answer.cursor, rightBits)) {
+        continue;
+      }
+      if (leftBits != rightBits) {
+        continue;
+      }
+      if (!looksTheSame.empty()) {
+        looksTheSame += ",";
+      }
+      looksTheSame += left.keyword + "=" + right.keyword;
+    }
+  }
+  EXPECT_EQ(looksTheSame, std::string(""));
+
   // And the failure this is really about, named directly rather than left to
   // the loop above: the arrow belongs to `default`. A keyword mapped onto
   // `IDC_ARROW` to stop it answering nothing is the same silence with a handle

package/native/tests/test_win32_peer_clip.cpp

@@ -0,0 +1,266 @@
+// Which pixels of a `<TextInput>`'s EDIT are still the EDIT's.
+//
+// The peer is a child window, so USER32 draws it after everything Direct2D
+// drew and the React tree has no say in it. `peerClip` is what works out the
+// region that puts the say back -- see win32/Win32PeerClip.h -- and it is pure
+// geometry over a view tree, so none of this needs a window, a control or
+// React Native.
+//
+// The two failures it exists to prevent are both things a person sees and a
+// test otherwise does not: a field in a half-scrolled list drawn over the
+// list's neighbour, and a field floating at full brightness over a modal.
+
+#include "TestHarness.h"
+
+#include "RnWin32View.h"
+#include "Win32PeerClip.h"
+
+#include <memory>
+#include <sstream>
+#include <string>
+#include <vector>
+
+using basalt::win32::peerClip;
+using basalt::win32::RnWin32View;
+
+namespace {
+
+class Tree {
+ public:
+  RnWin32View *box(float x, float y, float w, float h) {
+    auto view = std::make_unique<RnWin32View>(nextTag_++);
+    view->setFrame(x, y, w, h);
+    RnWin32View *raw = view.get();
+    views_.push_back(std::move(view));
+    return raw;
+  }
+
+  // A box that paints: `alpha` is the background's, which is the whole of what
+  // decides whether it covers a field under it.
+  RnWin32View *painted(float x, float y, float w, float h, float alpha) {
+    RnWin32View *view = box(x, y, w, h);
+    view->setBackgroundColor(0.0f, 0.0f, 0.0f, alpha, true);
+    return view;
+  }
+
+ private:
+  int32_t nextTag_ = 1;
+  std::vector<std::unique_ptr<RnWin32View>> views_;
+};
+
+std::string describe(const RECT &rect) {
+  std::ostringstream out;
+  out << rect.left << "," << rect.top << " " << rect.right << "," << rect.bottom;
+  return out.str();
+}
+
+} // namespace
+
+TEST(peer_clip_reports_the_field_where_the_tree_puts_it) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *pane = tree.box(40, 20, 300, 400);
+  RnWin32View *field = tree.box(10, 30, 200, 32);
+  root->insertChild(pane, 0);
+  pane->insertChild(field, 0);
+
+  const auto clip = peerClip(field, root);
+  EXPECT(clip.visible);
+  // Offsets accumulate down the chain, and the root's own frame is not part of
+  // them: these are client coordinates.
+  EXPECT_EQ(describe(clip.bounds), std::string("50,50 250,82"));
+  // Nothing clips and nothing paints over it, so the visible part is all of it.
+  EXPECT_EQ(describe(clip.clip), std::string("50,50 250,82"));
+  EXPECT_EQ(clip.occluders.size(), static_cast<size_t>(0));
+}
+
+TEST(peer_clip_narrows_a_field_half_scrolled_out_of_its_list) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *list = tree.box(0, 100, 300, 200);
+  list->setClipsChildren(true);
+  RnWin32View *field = tree.box(0, 180, 300, 40);
+  root->insertChild(list, 0);
+  list->insertChild(field, 0);
+
+  // Unscrolled the field is at y=280..320 and the list ends at y=300, so half
+  // of it is outside. This is the case the old rule got wrong: it hid a field
+  // only once it had left the list *entirely*, so the bottom 20 pixels went on
+  // being drawn over whatever came after the list.
+  const auto clip = peerClip(field, root);
+  EXPECT(clip.visible);
+  EXPECT_EQ(describe(clip.bounds), std::string("0,280 300,320"));
+  EXPECT_EQ(describe(clip.clip), std::string("0,280 300,300"));
+
+  // Scrolled until it is gone, and it is gone.
+  list->setScrollOffset(0, 400);
+  EXPECT(!peerClip(field, root).visible);
+
+  // And scrolled back so it sits inside, the clip is the whole field again.
+  list->setScrollOffset(0, 100);
+  const auto inside = peerClip(field, root);
+  EXPECT(inside.visible);
+  EXPECT_EQ(describe(inside.clip), std::string("0,180 300,220"));
+}
+
+TEST(peer_clip_is_empty_for_a_field_nothing_can_see) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *pane = tree.box(0, 0, 300, 400);
+  RnWin32View *field = tree.box(0, 0, 200, 32);
+  root->insertChild(pane, 0);
+  pane->insertChild(field, 0);
+
+  EXPECT(peerClip(field, root).visible);
+
+  field->setHidden(true);
+  EXPECT(!peerClip(field, root).visible);
+  field->setHidden(false);
+
+  // An ancestor hidden counts the same, which `display: none` on a pane is.
+  pane->setHidden(true);
+  EXPECT(!peerClip(field, root).visible);
+  pane->setHidden(false);
+
+  // Detached -- between a Remove and its Delete -- is not under the root, so
+  // the walk never reaches it.
+  pane->removeChild(field);
+  EXPECT(!peerClip(field, root).visible);
+}
+
+TEST(peer_clip_cuts_away_what_the_tree_paints_over_a_field) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *pane = tree.box(0, 0, 400, 600);
+  RnWin32View *field = tree.box(20, 40, 200, 32);
+  // The modal: a dimming backdrop over the whole window, rendered after the
+  // panes because that is where an overlay goes in a React tree.
+  RnWin32View *backdrop = tree.painted(0, 0, 800, 600, 0.63f);
+  root->insertChild(pane, 0);
+  pane->insertChild(field, 0);
+  root->insertChild(backdrop, 1);
+
+  const auto clip = peerClip(field, root);
+  EXPECT(clip.visible);
+  EXPECT_EQ(clip.occluders.size(), static_cast<size_t>(1));
+  EXPECT_EQ(describe(clip.occluders[0]), std::string("0,0 800,600"));
+
+  // A translucent backdrop counts. It has to: the field is a window and the
+  // backdrop is paint, so there is no blend the two can take part in, and an
+  // undimmed field over a modal is the bug this is here for.
+  //
+  // Fully transparent does not count -- that is a layout wrapper, which is
+  // most of a real tree.
+  backdrop->setBackgroundColor(0.0f, 0.0f, 0.0f, 0.0f, true);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(0));
+
+  // Neither does no background at all, which is not the same thing.
+  backdrop->setBackgroundColor(0.0f, 0.0f, 0.0f, 1.0f, false);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(0));
+
+  // Nor an invisible one, however solid its colour.
+  backdrop->setBackgroundColor(0.0f, 0.0f, 0.0f, 1.0f, true);
+  backdrop->setOpacity(0.0f);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(0));
+}
+
+TEST(peer_clip_ignores_everything_painted_before_the_field) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  // A solid pane behind the field, and the field's own background: both are
+  // painted first, and a field is not hidden by what is under it.
+  RnWin32View *behind = tree.painted(0, 0, 800, 600, 1.0f);
+  RnWin32View *pane = tree.painted(0, 0, 400, 600, 1.0f);
+  RnWin32View *field = tree.box(20, 40, 200, 32);
+  root->insertChild(behind, 0);
+  root->insertChild(pane, 1);
+  pane->insertChild(field, 0);
+
+  const auto clip = peerClip(field, root);
+  EXPECT(clip.visible);
+  EXPECT_EQ(clip.occluders.size(), static_cast<size_t>(0));
+}
+
+TEST(peer_clip_follows_z_index_rather_than_the_child_list) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *field = tree.box(0, 0, 200, 32);
+  RnWin32View *sheet = tree.painted(0, 0, 800, 600, 1.0f);
+  // The sheet is inserted first, so by mutation order it is painted first and
+  // covers nothing.
+  root->insertChild(sheet, 0);
+  root->insertChild(field, 1);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(0));
+
+  // zIndex restacks painting without touching the child list, and the answer
+  // has to follow the painting -- which is the same rule hit testing is under.
+  sheet->setZIndex(40);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(1));
+}
+
+TEST(peer_clip_narrows_an_occluder_to_its_own_clipping_ancestor) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *field = tree.box(0, 0, 400, 200);
+  // A panel after the field whose content is twice its height and clipped to
+  // it. What covers the field is the panel's visible part, not the child's
+  // full box -- the half outside the panel is not drawn anywhere.
+  RnWin32View *panel = tree.box(0, 0, 400, 100);
+  panel->setClipsChildren(true);
+  RnWin32View *content = tree.painted(0, 0, 400, 200, 1.0f);
+  root->insertChild(field, 0);
+  root->insertChild(panel, 1);
+  panel->insertChild(content, 0);
+
+  const auto clip = peerClip(field, root);
+  EXPECT_EQ(clip.occluders.size(), static_cast<size_t>(1));
+  EXPECT_EQ(describe(clip.occluders[0]), std::string("0,0 400,100"));
+}
+
+TEST(peer_clip_leaves_a_transformed_view_alone) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *field = tree.box(0, 0, 200, 32);
+  RnWin32View *card = tree.painted(0, 0, 800, 600, 1.0f);
+  root->insertChild(field, 0);
+  root->insertChild(card, 1);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(1));
+
+  // Rotated, its box is no longer a rectangle in these coordinates, and a
+  // region is rectangles. Guessing at a bounding box would hide more of the
+  // field than the card covers, so nothing is cut away at all -- the same
+  // decision the placement already makes about a transformed field.
+  const float rotated[16] = {0.0f,
+                             1.0f,
+                             0.0f,
+                             0.0f,
+                             -1.0f,
+                             0.0f,
+                             0.0f,
+                             0.0f,
+                             0.0f,
+                             0.0f,
+                             1.0f,
+                             0.0f,
+                             0.0f,
+                             0.0f,
+                             0.0f,
+                             1.0f};
+  card->setTransform(rotated);
+  EXPECT_EQ(peerClip(field, root).occluders.size(), static_cast<size_t>(0));
+}
+
+TEST(peer_clip_does_not_treat_the_fields_own_children_as_over_it) {
+  Tree tree;
+  RnWin32View *root = tree.box(0, 0, 800, 600);
+  RnWin32View *field = tree.box(0, 0, 200, 32);
+  RnWin32View *inside = tree.painted(0, 0, 200, 32, 1.0f);
+  root->insertChild(field, 0);
+  field->insertChild(inside, 0);
+
+  // Inside the field is not over it, and a field that cut itself away for its
+  // own content would never be visible at all.
+  const auto clip = peerClip(field, root);
+  EXPECT(clip.visible);
+  EXPECT_EQ(clip.occluders.size(), static_cast<size_t>(0));
+}

package/native/tests/test_win32_run_loop.cpp

@@ -0,0 +1,122 @@
+// The message loop, and the one thing it has to get right that is not
+// obvious. See win32/Win32RunLoopObserver.h.
+
+#include "TestHarness.h"
+
+#include "Win32RunLoopObserver.h"
+
+#include <windows.h>
+
+#include <chrono>
+
+namespace {
+
+constexpr UINT kFlood = WM_APP + 11;
+
+// A message-only window whose only message reposts itself, so the queue is
+// never observed empty. `flooding` ends it, since a message still in the
+// queue when the loop stops would be pumped by whatever runs next.
+bool gFlooding = true;
+long gFlooded = 0;
+
+LRESULT CALLBACK floodProc(HWND hwnd, UINT message, WPARAM w, LPARAM l) {
+  if (message == kFlood) {
+    gFlooded++;
+    // A ceiling, so that a loop which never beats fails rather than hangs:
+    // the beat is what stops the flood and posts WM_QUIT, and a regression
+    // here is precisely a beat that never happens.
+    if (gFlooded > 50000) {
+      gFlooding = false;
+    }
+    if (gFlooding) {
+      PostMessageW(hwnd, kFlood, 0, 0);
+    }
+    return 0;
+  }
+  return DefWindowProcW(hwnd, message, w, l);
+}
+
+HWND makeFloodWindow() {
+  WNDCLASSEXW windowClass{};
+  windowClass.cbSize = sizeof(windowClass);
+  windowClass.lpfnWndProc = floodProc;
+  windowClass.hInstance = GetModuleHandleW(nullptr);
+  windowClass.lpszClassName = L"BasaltRunLoopFloodTest";
+  RegisterClassExW(&windowClass);
+  return CreateWindowExW(0,
+                         L"BasaltRunLoopFloodTest",
+                         L"",
+                         0,
+                         0,
+                         0,
+                         0,
+                         0,
+                         HWND_MESSAGE,
+                         nullptr,
+                         GetModuleHandleW(nullptr),
+                         nullptr);
+}
+
+void dropFloodWindow(HWND window) {
+  gFlooding = false;
+  DestroyWindow(window);
+  UnregisterClassW(L"BasaltRunLoopFloodTest", GetModuleHandleW(nullptr));
+  // Whatever is left of the flood, so the next test's pump does not inherit
+  // it.
+  MSG message;
+  while (PeekMessageW(&message, nullptr, 0, 0, PM_REMOVE)) {
+  }
+}
+
+} // namespace
+
+TEST(run_loop_beats_once_when_the_queue_empties) {
+  int beats = 0;
+  PostMessageW(nullptr, WM_NULL, 0, 0);
+  const int code = basalt::runMessageLoop([&beats] {
+    beats++;
+    PostQuitMessage(7);
+  });
+  EXPECT_EQ(code, 7);
+  EXPECT_EQ(beats, 1);
+}
+
+TEST(run_loop_beats_on_a_queue_that_never_empties) {
+  // The regression this file exists for.
+  //
+  // The loop drains before it beats, which is what "BeforeWaiting" means and
+  // what React Native's event queue is flushed by. An app that paints
+  // continuously -- kino, whose preview is a Skia `<Canvas>`: 120 WM_PAINT
+  // and 250 posted work items a second while idle -- never lets the drain
+  // finish, so the beat never ran and events sat in the queue. What that
+  // looked like from outside was a button that usually worked: one scripted
+  // tap in three did nothing, and a real click rather more often than that.
+  //
+  // Without the bound in the loop this test does not fail slowly. It never
+  // beats at all, so it never posts WM_QUIT, and the deadline below is the
+  // only thing that ends it.
+  gFlooding = true;
+  gFlooded = 0;
+  HWND window = makeFloodWindow();
+  EXPECT(window != nullptr);
+  PostMessageW(window, kFlood, 0, 0);
+
+  int beats = 0;
+  const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(2);
+  basalt::runMessageLoop([&] {
+    beats++;
+    // Several, so this is about a loop that keeps beating rather than one
+    // that beat once on the way in.
+    if (beats >= 4 || std::chrono::steady_clock::now() > deadline) {
+      gFlooding = false;
+      PostQuitMessage(0);
+    }
+  });
+
+  EXPECT(beats >= 4);
+  // ...and the flood really was running, so the beats above happened in spite
+  // of it rather than after it ran out.
+  EXPECT(gFlooded > 100);
+
+  dropFloodWindow(window);
+}