basalt-win32 0.2.1 → 0.2.3

package/native/win32/Win32AnimationChoreographer.cpp

@@ -1,31 +1,17 @@
 #include "Win32AnimationChoreographer.h"
 
-#include <windows.h>
+#include "Win32UiTimer.h"
 
 #include <chrono>
 
 namespace basalt {
 namespace {
 
-// Roughly sixty hertz. SetTimer's resolution is the message queue's -- it
-// cannot do better than about ten to sixteen milliseconds and it coalesces --
-// so this is an upper bound on the frame rate rather than a promise of one.
-// See the header for what would be needed to do it properly.
-constexpr UINT kFrameIntervalMs = 16;
-
-// SetTimer's callback carries the timer id and nothing else, so the
-// choreographer has to be found from it. One host means one choreographer, and
-// a map would be pretending otherwise.
-Win32AnimationChoreographer *&currentChoreographer() {
-  static Win32AnimationChoreographer *instance = nullptr;
-  return instance;
-}
-
-void CALLBACK onTimer(HWND, UINT, UINT_PTR, DWORD) {
-  if (auto *choreographer = currentChoreographer()) {
-    choreographer->onFrame();
-  }
-}
+// Roughly sixty hertz. The delay is a floor rather than a promise -- the frame
+// is posted to the loop and arrives behind whatever the loop is already
+// holding -- so this is an upper bound on the frame rate. See the header for
+// what would be needed to do it properly.
+constexpr unsigned kFrameIntervalMs = 16;
 
 } // namespace
 
@@ -37,28 +23,25 @@ void Win32AnimationChoreographer::resume() {
   if (running_.exchange(true)) {
     return;
   }
-  currentChoreographer() = this;
-  // A timer with no window: the callback is delivered as WM_TIMER to the
-  // thread's queue and dispatched by the loop, which means it lands on the UI
-  // thread like everything else and needs no synchronisation of its own.
-  timer_ = static_cast<std::uintptr_t>(SetTimer(nullptr, 0, kFrameIntervalMs, onTimer));
+  // Not `SetTimer`. A sixty-hertz WM_TIMER is exactly the arrangement that
+  // stops working in an app that repaints continuously, which is to say in
+  // every app with an animation worth running. See win32/Win32UiTimer.h.
+  timer_ = scheduleUiTimer(kFrameIntervalMs, true, [this] { onFrame(); });
 }
 
 void Win32AnimationChoreographer::pause() {
   if (!running_.exchange(false)) {
     return;
   }
-  if (timer_ != 0) {
-    KillTimer(nullptr, static_cast<UINT_PTR>(timer_));
-    timer_ = 0;
-  }
+  // Before this returns, nothing of ours is still in flight: `cancelUiTimer`
+  // waits out a delivery already on a pool thread, which is what makes the
+  // `this` captured above safe to destroy afterwards.
+  cancelUiTimer(timer_);
+  timer_ = 0;
 }
 
 void Win32AnimationChoreographer::detach() {
   pause();
-  if (currentChoreographer() == this) {
-    currentChoreographer() = nullptr;
-  }
 }
 
 void Win32AnimationChoreographer::onFrame() {

package/native/win32/Win32AnimationChoreographer.h

@@ -12,8 +12,8 @@
 // own thread, because DwmFlush blocks, and a blocked UI thread is worse than a
 // slightly wrong frame interval.
 //
-// So this is a multimedia timer at sixty hertz, and it is worth being clear
-// that this is a placeholder rather than a design. `docs/BACKLOG.md` already
+// So this is a timer at sixty hertz, and it is worth being clear that this is
+// a placeholder rather than a design. `docs/BACKLOG.md` already
 // records that worklets and Reanimated run on a sixteen-millisecond timer on
 // *both* other desktops for a related reason -- each platform's display link
 // belongs to React Native's own choreographer and pauses when React Native has
@@ -52,10 +52,13 @@ class Win32AnimationChoreographer final : public facebook::react::AnimationChore
 
  private:
   std::atomic<bool> running_{false};
-  // A UINT_PTR from SetTimer, held as an integer so this header needs no
-  // windows.h -- which would otherwise reach every translation unit that
-  // constructs a host.
-  std::uintptr_t timer_{0};
+  // A `basalt::UiTimerId` rather than a `SetTimer` handle, and not for
+  // tidiness: WM_TIMER ranks below WM_PAINT, so on this timer an app that
+  // repaints continuously -- anything with a `<Canvas>` -- stopped getting
+  // animation frames at all. See win32/Win32UiTimer.h. Held as a plain
+  // integer so this header needs no windows.h, which would otherwise reach
+  // every translation unit that constructs a host.
+  std::uint64_t timer_{0};
 };
 
 } // namespace basalt

package/native/win32/Win32AppWindow.h

@@ -0,0 +1,36 @@
+// Which HWND a surface id means.
+//
+// The same seam AppKitAppWindow.h and GtkAppWindow.h describe, written for
+// this toolkit and for the same reason: the registry of open windows is
+// `main_win32.cpp`'s, and everything that resolves one is compiled into the
+// mounting library, which the host links rather than the other way round. So
+// the host installs a lookup at startup and this is what the window module
+// asks.
+//
+// Not installed is the normal case for a test binary: it opens no window, and
+// should not grow a registry to keep compiling. `win32AppWindowFor` falls back
+// to the active window, which is what every caller here did before windows had
+// ids.
+
+#pragma once
+
+#include <react/renderer/core/ReactPrimitives.h>
+
+#include <functional>
+
+#include <windows.h>
+
+namespace basalt {
+
+// The app's own window, by the rule this host has always used: the active
+// window, falling back to the foreground one. UI thread only.
+HWND win32AppWindow();
+
+using Win32AppWindowLookup = std::function<HWND(facebook::react::SurfaceId)>;
+void setWin32AppWindowLookup(Win32AppWindowLookup lookup);
+
+// The window with this surface id, or the app's own for `kAppWindow` and for
+// an id the lookup does not know. UI thread only.
+HWND win32AppWindowFor(facebook::react::SurfaceId window);
+
+} // namespace basalt

package/native/win32/Win32Cursors.cpp

@@ -244,20 +244,6 @@ HCURSOR cursorFromArt(const Art &art, int hotX, int hotY) {
   return cursor;
 }
 
-// `%SystemRoot%\Cursors\aero_link.cur`, the shell's own shortcut cursor, which
-// is the one of the six Windows ships as a file with a name rather than as an
-// ordinal inside a DLL. Null when it is not there, and the caller draws its own.
-HCURSOR cursorFromSystemFile(const wchar_t *leaf) {
-  wchar_t path[MAX_PATH]{};
-  const UINT length = GetWindowsDirectoryW(path, MAX_PATH);
-  if (length == 0 || length >= MAX_PATH) {
-    return nullptr;
-  }
-  std::wstring full(path);
-  full += L"\\Cursors\\";
-  full += leaf;
-  return LoadCursorFromFileW(full.c_str());
-}
 
 HCURSOR drawnCursorFor(const std::string &keyword) {
   if (keyword == "copy") {
@@ -267,9 +253,19 @@ HCURSOR drawnCursorFor(const std::string &keyword) {
     return cursorFromArt(contextMenuArt(), 0, 0);
   }
   if (keyword == "alias") {
-    if (HCURSOR shipped = cursorFromSystemFile(L"aero_link.cur")) {
-      return shipped;
-    }
+    // Drawn, like the other five, and not `%SystemRoot%\Cursors\aero_link.cur`.
+    //
+    // That file was preferred here on the reasoning that a real name beats an
+    // unnamed ordinal inside shell32, which is sound and is still why nothing
+    // else reaches into the shell. What it missed is what the file contains:
+    // on Windows 11 aero_link.cur is "Link Select", the pointing hand -- the
+    // same cursor `pointer` already gets from IDC_HAND. So `alias` and
+    // `pointer` came back pixel for pixel identical, and CSS means two
+    // different things by them.
+    //
+    // The art below is the shape `alias` is supposed to be: an arrow with the
+    // shortcut badge turning up and to the right. It was already written and
+    // never ran, because the file always loaded.
     return cursorFromArt(aliasArt(), 0, 0);
   }
   if (keyword == "cell") {

package/native/win32/Win32DropTarget.cpp

@@ -490,7 +490,10 @@ facebook::react::Tag dropTargetAt(win32::RnWin32View *root,
   }
   // Deepest first, which is the rule: a drop target inside another wins.
   for (auto it = path.rbegin(); it != path.rend(); ++it) {
-    const std::uint16_t wanted = dropAcceptsFrom((*it)->nativeId());
+    // The `nativeID` marker and the view's own declared kinds, which is how a
+    // <TextInput acceptDragAndDropTypes> joins this walk without an id.
+    const std::uint16_t wanted =
+        static_cast<std::uint16_t>(dropAcceptsFrom((*it)->nativeId()) | (*it)->dropAccepts());
     if (wanted != DropAcceptsNone && (wanted & accepts) != 0) {
       return static_cast<facebook::react::Tag>((*it)->tag());
     }

package/native/win32/Win32MenuBar.cpp

@@ -342,7 +342,9 @@ bool handleMenuCommand(unsigned int command) {
       PostMessageW(window, WM_CLOSE, 0, 0);
       return true;
     case kRoleBase + 12:
-      setWindowFullScreen(!windowBounds().fullScreen);
+      // The app's own window: a menu role acts on the window the menu bar
+      // belongs to, which is that one. See core/WindowControl.h.
+      setWindowFullScreen(kAppWindow, !windowBounds(kAppWindow).fullScreen);
       return true;
     default:
       return false;

package/native/win32/Win32MountingManager.cpp

@@ -1,3 +1,6 @@
+#include "AccessibilityRole.h"
+#include "KeyboardFocusable.h"
+#include "ImagePlaceholder.h"
 #include "Win32MountingManager.h"
 
 #include "BackgroundLayers.h"
@@ -15,7 +18,10 @@
 #include "PlatformServices.h"
 #include "UIManagerAccess.h"
 
-#ifdef BASALT_HAS_SKIA
+// Either Skia: the 2.x peer in this package or the 3.x one in basalt-skia,
+// which share this header's two functions and are never both linked. See
+// Win32SkiaPeer.h.
+#if defined(BASALT_HAS_SKIA) || BASALT_HAS_SKIA_GRAPHITE
 #include "Win32SkiaPeer.h"
 #endif
 
@@ -339,11 +345,13 @@ void Win32MountingManager::forgetTag(Tag tag) {
   scrollViews_.remove(tag);
   textInputs_.remove(tag);
   imageUris_.erase(tag);
+  imagePlaceholders_.erase(tag);
+  imageLoaded_.erase(tag);
   switchValues_.erase(tag);
   labels_.forget(tag);
   liveRegions_.forget(tag);
   liveRegionLabels_.erase(tag);
-#ifdef BASALT_HAS_SKIA
+#if defined(BASALT_HAS_SKIA) || BASALT_HAS_SKIA_GRAPHITE
   // Unregisters the canvas. This is the one moment a view is known to be
   // finished with, and a canvas left registered is a surface the package will
   // keep rendering into for a tag nothing will ever draw again.
@@ -360,7 +368,7 @@ void Win32MountingManager::updateView(RnWin32View *view, const ShadowView &shado
   applyText(view, shadowView);
   applyImage(view, shadowView);
   applyAccessibility(view, shadowView);
-#ifdef BASALT_HAS_SKIA
+#if defined(BASALT_HAS_SKIA) || BASALT_HAS_SKIA_GRAPHITE
   // After applyProps, which is what puts nativeID on the view -- a canvas
   // registers itself by that id and cannot attach before it is there. The size
   // it reads comes from the shadow view rather than from the frame
@@ -869,6 +877,9 @@ void Win32MountingManager::applyImage(RnWin32View *view, const ShadowView &shado
   const facebook::react::ImageSource source =
       props->sources.empty() ? facebook::react::ImageSource{} : props->sources.front();
   const std::string uri = source.uri;
+  // `defaultSource`, drawn until the source lands and kept if it never does.
+  // See core/ImagePlaceholder.h for which of the two props this is.
+  const std::string placeholder = basalt::imagePlaceholderUri(*props);
 
   // `tintColor`, applied before the load rather than in its callback: the tint
   // is a prop and the image is a loader's answer, and either can arrive first.
@@ -911,6 +922,8 @@ void Win32MountingManager::applyImage(RnWin32View *view, const ShadowView &shado
     return;
   }
   imageUris_[shadowView.tag] = uri;
+  imagePlaceholders_[shadowView.tag] = placeholder;
+  imageLoaded_.erase(shadowView.tag);
 
   if (uri.empty()) {
     view->setImage(nullptr, fit);
@@ -923,6 +936,38 @@ void Win32MountingManager::applyImage(RnWin32View *view, const ShadowView &shado
   // the change did not take.
   view->setImage(nullptr, fit);
 
+  // Then the placeholder, if the app named one, so the blank box above is as
+  // short as the loader is slow. A bundled asset answers from the cache on
+  // this thread, which makes it the same frame.
+  //
+  // Guarded on the real image not having arrived: both loads are asynchronous
+  // and a slow placeholder must not paint over the image it stood in for.
+  if (!placeholder.empty() && uri != placeholder) {
+    const Tag placeholderTag = shadowView.tag;
+    imageLoader_->load(
+        placeholder,
+        [this, placeholderTag, fit, placeholder](std::shared_ptr<win32::RnWin32Image> image,
+                                                 const std::string &) {
+          if (image == nullptr || imageLoaded_.count(placeholderTag) != 0) {
+            return;
+          }
+          const auto still = imagePlaceholders_.find(placeholderTag);
+          if (still == imagePlaceholders_.end() || still->second != placeholder) {
+            return;
+          }
+          RnWin32View *target = viewForTag(placeholderTag);
+          if (target == nullptr) {
+            return;
+          }
+          target->setImage(image, fit);
+          // The same reason the load callback below calls it: the bytes
+          // arrived on their own clock and only the host has the HWND.
+          if (onDidMount_) {
+            onDidMount_();
+          }
+        });
+  }
+
   // `<Image>`'s load events, which this host emitted none of until 2026-10-10:
   // `onLoadStart`, `onProgress`, `onLoad`, `onError` and `onLoadEnd` all
   // reached JavaScript on the other two hosts and nothing here ever dispatched
@@ -984,7 +1029,20 @@ void Win32MountingManager::applyImage(RnWin32View *view, const ShadowView &shado
         const bool stillWanted =
             target != nullptr && current != imageUris_.end() && current->second == uri;
         if (stillWanted) {
-          target->setImage(image, fit);
+          // A failed load leaves the placeholder where it is rather than
+          // clearing to nothing, which is `RCTImageComponentView`'s behaviour:
+          // a broken remote image shows what the app chose to show instead of
+          // an empty box.
+          const auto standing = imagePlaceholders_.find(tag);
+          const bool keepPlaceholder = image == nullptr &&
+                                       standing != imagePlaceholders_.end() &&
+                                       !standing->second.empty();
+          if (image != nullptr) {
+            imageLoaded_.insert(tag);
+          }
+          if (!keepPlaceholder) {
+            target->setImage(image, fit);
+          }
           applyAnimation(target, uri);
           // The screen is stale and no transaction is coming: the bytes arrived
           // on their own clock, after the mount that asked for them. On GTK and
@@ -1041,8 +1099,22 @@ win32::RnAccessibleFlag toFlag(bool value) {
 std::string effectiveRole(const ShadowView &shadowView) {
   if (const auto props =
           std::dynamic_pointer_cast<const facebook::react::AccessibilityProps>(shadowView.props)) {
-    if (!props->accessibilityRole.empty()) {
-      return props->accessibilityRole;
+    const std::string asked = basalt::accessibilityRoleName(*props);
+    if (!asked.empty()) {
+      return asked;
+    }
+  }
+  // Then the paragraph's own fragments, which is where a nested <Text>'s role
+  // lands: `TextAttributes` carries one per run, and a paragraph every fragment
+  // of which agrees *is* that role. Before the inference below, so a paragraph
+  // whose runs all say "header" is a header rather than generic text. See
+  // core/AccessibilityRole.h for why agreement and not the first one.
+  if (const auto state =
+          std::dynamic_pointer_cast<const facebook::react::ConcreteState<facebook::react::ParagraphState>>(
+              shadowView.state)) {
+    const std::string fragments = basalt::fragmentRoleName(state->getData().attributedString);
+    if (!fragments.empty()) {
+      return fragments;
     }
   }
   if (shadowView.componentName != nullptr) {
@@ -1082,6 +1154,9 @@ void Win32MountingManager::applyAccessibility(RnWin32View *view, const ShadowVie
   info.testId = props->testId;
   // `accessibilityViewIsModal`, which UIA calls a dialog.
   info.modal = props->accessibilityViewIsModal;
+  // `accessibilityLanguage`, as the BCP-47 tag the app wrote. The conversion
+  // to the LCID UIA wants happens where the culture property is answered.
+  info.language = props->accessibilityLanguage;
 
   const auto &state = props->accessibilityState;
   if (state.has_value()) {
@@ -1137,7 +1212,7 @@ void Win32MountingManager::applyAccessibility(RnWin32View *view, const ShadowVie
   // that cannot be operated rather than stopping on one that does nothing.
   const basalt::ControlState control = basalt::controlStateOf(shadowView);
   const bool isControl = control.kind == basalt::ControlKind::Switch && !control.disabled;
-  view->setFocusable((props->accessible || isControl) && !props->accessibilityElementsHidden);
+  view->setFocusable(basalt::keyboardFocusable(*props, isControl));
 }
 
 void Win32MountingManager::applyLayoutMetrics(RnWin32View *view, const ShadowView &shadowView) {

package/native/win32/Win32MountingManager.h

@@ -34,6 +34,7 @@
 #include <functional>
 #include <string>
 #include <unordered_map>
+#include <unordered_set>
 
 namespace basalt {
 
@@ -190,6 +191,10 @@ class Win32MountingManager final : public facebook::react::IMountingManager,
   // changed only layout does not restart the load and make the image flicker
   // whenever its parent resizes. Both other platforms keep the same map.
   std::unordered_map<facebook::react::Tag, std::string> imageUris_;
+  // `defaultSource` per view, and which views have their real image. See
+  // core/ImagePlaceholder.h.
+  std::unordered_map<facebook::react::Tag, std::string> imagePlaceholders_;
+  std::unordered_set<facebook::react::Tag> imageLoaded_;
 
   // Scroll offsets, the unthrottled state write-back, the wheel and the
   // commands. Constructed with a lookup into this object's own emitter registry

package/native/win32/Win32PeerClip.cpp

@@ -0,0 +1,153 @@
+#include "Win32PeerClip.h"
+
+#include "RnWin32View.h"
+
+#include <algorithm>
+#include <cmath>
+
+namespace basalt::win32 {
+
+namespace {
+
+RECT boxOf(double x, double y, double width, double height) {
+  RECT rect{};
+  rect.left = static_cast<LONG>(std::lround(x));
+  rect.top = static_cast<LONG>(std::lround(y));
+  rect.right = rect.left + static_cast<LONG>(std::lround(width));
+  rect.bottom = rect.top + static_cast<LONG>(std::lround(height));
+  return rect;
+}
+
+bool isEmpty(const RECT &rect) {
+  return rect.right <= rect.left || rect.bottom <= rect.top;
+}
+
+RECT intersect(const RECT &a, const RECT &b) {
+  RECT out{};
+  out.left = std::max(a.left, b.left);
+  out.top = std::max(a.top, b.top);
+  out.right = std::min(a.right, b.right);
+  out.bottom = std::min(a.bottom, b.bottom);
+  if (isEmpty(out)) {
+    return RECT{0, 0, 0, 0};
+  }
+  return out;
+}
+
+// Whether this view puts something over the whole of its own box.
+//
+// A background colour with any alpha at all, and nothing else -- see the
+// header for why the bar is "not transparent" rather than "opaque", and why a
+// transformed view is left alone instead of being approximated by its bounding
+// box.
+bool covers(const RnWin32View *view) {
+  if (!view->hasBackgroundColor() || view->hasTransform()) {
+    return false;
+  }
+  if (view->opacity() <= 0.0f) {
+    return false;
+  }
+  return view->backgroundColor()[3] > 0.0f;
+}
+
+struct Walk {
+  const RnWin32View *target{nullptr};
+  PeerClip *out{nullptr};
+  // Set when the target has been reached, which is what divides the tree into
+  // "painted before it", which cannot cover it, and "painted after it", which
+  // can. One flag is enough because painting order is a single sequence.
+  bool seen{false};
+};
+
+// `origin` is where this view's parent puts its children, already scrolled.
+void visit(RnWin32View *view, double originX, double originY, const RECT &clip, Walk &walk) {
+  if (view == nullptr || view->hidden()) {
+    return;
+  }
+
+  const double x = originX + view->frame().x;
+  const double y = originY + view->frame().y;
+  const RECT box = boxOf(x, y, view->frame().width, view->frame().height);
+
+  if (view == walk.target) {
+    const RECT visible = intersect(box, clip);
+    if (isEmpty(visible)) {
+      return;
+    }
+    walk.out->visible = true;
+    walk.out->bounds = box;
+    walk.out->clip = visible;
+    // Its own subtree is not walked: a child of a `<TextInput>` is inside the
+    // field rather than over it, and the field has none in any real tree.
+    walk.seen = true;
+    return;
+  }
+
+  if (walk.seen && covers(view)) {
+    const RECT over = intersect(box, clip);
+    if (!isEmpty(over)) {
+      walk.out->occluders.push_back(over);
+    }
+  }
+
+  RECT childClip = clip;
+  if (view->clipsChildren()) {
+    childClip = intersect(clip, box);
+    if (isEmpty(childClip)) {
+      // Nothing inside can be seen, and nothing inside can cover anything
+      // either -- but the target may still be in there, and if it is then it is
+      // off screen, which is what not finding it already means.
+      return;
+    }
+  }
+
+  const double childX = x - view->scrollX();
+  const double childY = y - view->scrollY();
+  for (RnWin32View *child : view->childrenInPaintOrder()) {
+    visit(child, childX, childY, childClip, walk);
+  }
+}
+
+} // namespace
+
+PeerClip peerClip(RnWin32View *view, RnWin32View *root) {
+  PeerClip result{};
+  if (view == nullptr || root == nullptr) {
+    return result;
+  }
+
+  // The root's own frame is not part of these coordinates: the surface root is
+  // the client area, and a peer's position is measured from its top-left. So
+  // the walk starts inside it rather than at it, which also means a `view` that
+  // *is* the root is not a field and comes back invisible.
+  if (root->hidden()) {
+    return result;
+  }
+
+  // Unbounded unless the root says otherwise, which is the rule every other
+  // ancestor is under. Clipping to the client area regardless would be defen-
+  // sible and is not done here: a surface that has never been laid out has a
+  // zero frame, and "every field is invisible" is a worse answer than "a field
+  // outside the window is placed outside the window", which USER32 handles.
+  constexpr LONG kUnbounded = 1 << 28;
+  RECT clip{-kUnbounded, -kUnbounded, kUnbounded, kUnbounded};
+  if (root->clipsChildren()) {
+    clip = boxOf(0.0, 0.0, root->frame().width, root->frame().height);
+    if (isEmpty(clip)) {
+      return result;
+    }
+  }
+  Walk walk{view, &result, false};
+  const double childX = -static_cast<double>(root->scrollX());
+  const double childY = -static_cast<double>(root->scrollY());
+  for (RnWin32View *child : root->childrenInPaintOrder()) {
+    visit(child, childX, childY, clip, walk);
+  }
+
+  if (!result.visible) {
+    return PeerClip{};
+  }
+  return result;
+}
+
+} // namespace basalt::win32

package/native/win32/Win32PeerClip.h

@@ -0,0 +1,92 @@
+// Where a child-window peer is allowed to paint.
+//
+// A `<TextInput>` on this host is a real EDIT control, so it is a child window
+// rather than something Direct2D draws. That buys the IME, the clipboard and
+// every binding a Windows user expects, and it costs the one thing every other
+// view gets for free: a place in the painting order. A child window is drawn by
+// USER32 after the parent's client area, so it sits above everything the React
+// tree drew, whatever the tree says. Two things follow, and a person sees both:
+//
+//   - A field in a `<ScrollView>` does not clip to it. Scroll the list until
+//     the field is half out and the half that should be gone goes on being
+//     drawn over the list's neighbour.
+//   - A field cannot be covered. Open a modal over a pane that has one and the
+//     field floats on top of the modal, at full brightness, still editable.
+//
+// Both are the same missing fact -- which pixels of the field are still the
+// field's -- and Windows has somewhere to put it: `SetWindowRgn`. A window with
+// a region is displayed only inside it, and clicks outside it fall through to
+// the parent. So the job is to work the region out from the view tree, which is
+// what this file is: pure geometry over `RnWin32View`, with no window, no
+// control and no React Native in it, so that it can be tested with none of
+// them.
+//
+// ## What counts as covering it
+//
+// Clipping is exact: a clipping ancestor's box is a rectangle and the
+// intersection of rectangles is the answer.
+//
+// Occlusion is not, and cannot be. The right behaviour for a field under
+// kino's modal scrim -- `#000000A0` over the whole window -- is for the field
+// to be *dimmed*, and a child window cannot be dimmed by something painted into
+// its parent: the two are composited by USER32, in that order, with no blend to
+// take part in. The choice is therefore between showing the field undimmed and
+// hiding it, and hiding it is the better wrong answer: an undimmed field over a
+// modal is the bug people report, while a field that goes quiet under a scrim
+// reads as part of the modal.
+//
+// So anything painted after the field that is not fully transparent counts as
+// covering it. That is deliberately more eager than "opaque": a 63%-black
+// backdrop blends to something no child window can match, so there is nothing
+// to be gained by letting it show through at 100%.
+//
+// What does *not* count: a view with no background at all, which is every
+// layout wrapper in a real tree and the reason this rule produces no false
+// positives in practice, and a transformed view, whose box is not a rectangle
+// in these coordinates and which is therefore left alone rather than guessed
+// at. A `<Text>` drawn over a field is also left alone -- glyphs are not a box.
+//
+// ## Transforms
+//
+// Ignored throughout, as `Win32TextInputManager` already ignores them when it
+// places the peer: a window cannot be rotated, so a transformed field's peer
+// sits where the untransformed one would, and clipping it to a rotated
+// ancestor's bounding box would only move the error around.
+
+#pragma once
+
+#include <windows.h>
+
+#include <vector>
+
+namespace basalt::win32 {
+
+class RnWin32View;
+
+// Where `view`'s peer may paint, all in the surface root's coordinates.
+struct PeerClip {
+  // False when the view is not on screen at all: hidden, detached, or scrolled
+  // entirely out of a clipping ancestor. Nothing else in the struct means
+  // anything then.
+  bool visible{false};
+
+  // The view's own box, unclipped. This is where the control goes -- a control
+  // narrowed to its visible part would lay its text out in the wrong width.
+  RECT bounds{};
+
+  // `bounds` narrowed by every clipping ancestor. Never empty when `visible`.
+  RECT clip{};
+
+  // Boxes painted after the view that cover part of it, already narrowed to
+  // their own clipping ancestors. Each is taken out of the region.
+  std::vector<RECT> occluders{};
+};
+
+// Walks the tree from `root` once, in painting order, and answers for `view`.
+//
+// `root` is the surface root, whose coordinates are the window's client
+// coordinates on this host. A view that is not under `root` comes back
+// invisible, which is what a peer between a Remove and its Delete looks like.
+PeerClip peerClip(RnWin32View *view, RnWin32View *root);
+
+} // namespace basalt::win32