basalt-core 0.0.0-rc5 → 0.2.0

package/native/core/SafeAreaComponent.h

@@ -0,0 +1,105 @@
+// react-native-safe-area-context's provider view, as a Fabric component.
+//
+// ## Why this is the file that makes navigation work
+//
+// `SafeAreaProvider` renders `insets != null ? children : null`, and `insets`
+// starts null unless the application passed `initialMetrics`. The only other
+// thing that fills it is an `onInsetsChange` event from this component. With no
+// native half, nothing ever fires it, so the provider renders null forever and
+// every screen beneath it stays unmounted.
+//
+// That is why an app using react-navigation or expo-router showed an empty
+// window and logged nothing: there is no error anywhere in that path, just a
+// provider waiting for a platform that never answers. Measured on 2026-10-01
+// before this existed; see docs/backlog/ecosystem.md.
+//
+// ## Why the event comes from layout rather than from a host
+//
+// Insets on a phone are the notch and the home indicator, which the toolkit
+// knows and C++ does not. A desktop window has neither, so the insets are zero
+// on all three platforms and the only unknown is the frame, which is this
+// view's own layout. Both are therefore available here, in the shadow node,
+// and a per-host mounting peer would be three copies of the same zero.
+//
+// The provider is styled `flex: 1` by the library, so its frame is the surface,
+// which is what `SafeAreaFrameContext` is supposed to carry.
+//
+// If a desktop later grows a real inset -- a client-side-decorated title bar
+// drawn over the content, say -- this is the place it would come from, and it
+// would need a host behind it at that point.
+
+#pragma once
+
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/components/view/ViewEventEmitter.h>
+#include <react/renderer/components/view/ViewProps.h>
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+#include <react/renderer/core/LayoutContext.h>
+#include <react/renderer/graphics/Rect.h>
+#include <ReactCommon/TurboModule.h>
+
+namespace facebook::react {
+
+extern const char SafeAreaProviderComponentName[];
+
+// `onInsetsChange`, whose payload is `{frame: {x, y, width, height}, insets:
+// {top, right, bottom, left}}`. The names are the library's and an app reads
+// them straight off `event.nativeEvent`, so they are a contract rather than a
+// choice.
+class SafeAreaProviderEventEmitter : public ViewEventEmitter {
+ public:
+  using ViewEventEmitter::ViewEventEmitter;
+
+  void onInsetsChange(const Rect &frame, const EdgeInsets &insets) const;
+};
+
+// No props of its own. `onInsetsChange` is an event rather than a prop, and
+// everything else the library sets on it is ordinary view styling, so
+// `ViewProps` parses the lot.
+class SafeAreaProviderShadowNode final
+    : public ConcreteViewShadowNode<SafeAreaProviderComponentName, ViewProps,
+                                    SafeAreaProviderEventEmitter> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+
+  static ShadowNodeTraits BaseTraits() {
+    return ConcreteViewShadowNode::BaseTraits();
+  }
+
+  void layout(LayoutContext layoutContext) override;
+};
+
+using SafeAreaProviderComponentDescriptor =
+    ConcreteComponentDescriptor<SafeAreaProviderShadowNode>;
+
+} // namespace facebook::react
+
+namespace basalt {
+
+// The window the application started with, which a host reports once it has
+// one. Zero means not yet known, and the module then omits
+// `initialWindowMetrics` rather than claiming a zero-sized window: the field is
+// optional in the library's own spec, and absent is a state it already handles.
+void setInitialWindowFrame(double width, double height);
+
+// `RNCSafeAreaContext`, which the library asks for with `TurboModuleRegistry.get`.
+//
+// A null answer is survivable -- that is `get` rather than `getEnforcing` -- and
+// until now that is what it got, which is why the warning appeared in every log.
+// What the module is actually for is `initialWindowMetrics`, the export an app
+// passes to `SafeAreaProvider` so the first frame is right rather than corrected
+// one pass later. Nothing else in the library needs it.
+class DesktopSafeAreaModule : public facebook::react::TurboModule {
+ public:
+  static constexpr auto kModuleName = "RNCSafeAreaContext";
+
+  explicit DesktopSafeAreaModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+
+ private:
+  static facebook::jsi::Value getConstants(facebook::jsi::Runtime &runtime,
+                                           facebook::react::TurboModule &module,
+                                           const facebook::jsi::Value *args,
+                                           size_t count);
+};
+
+} // namespace basalt

package/native/core/ScreensComponent.cpp

@@ -0,0 +1,201 @@
+#include "ScreensComponent.h"
+
+#include <react/renderer/core/LayoutableShadowNode.h>
+#include <react/renderer/core/propsConversions.h>
+
+#include <algorithm>
+#include <string>
+
+namespace facebook::react {
+
+extern const char RNSScreenComponentName[] = "RNSScreen";
+
+RNSScreenProps::RNSScreenProps(const PropsParserContext &context,
+                               const RNSScreenProps &sourceProps,
+                               const RawProps &rawProps)
+    : ViewProps(context, sourceProps, rawProps),
+      activityState(convertRawProp(context, rawProps, "activityState",
+                                   sourceProps.activityState, -1.0f)) {
+  // `transparentModal` and `containedTransparentModal` are the two that show
+  // what is under them. Matching on the substring rather than listing both
+  // means a presentation added upstream with the same word in it behaves the
+  // way its name says.
+  const auto presentation = convertRawProp(
+      context, rawProps, "stackPresentation", std::string{}, std::string{});
+  seeThrough = presentation.find("ransparent") != std::string::npos;
+
+  // Only an explicit 0 hides it. The default is -1, which the library uses for
+  // a screen it is not managing, and 1 is a screen mid-transition that still
+  // has to be on screen to be transitioned.
+  if (activityState == 0.0f) {
+    yogaStyle.setDisplay(yoga::Display::None);
+  }
+}
+
+extern const char RNSScreenContainerComponentName[] = "RNSScreenContainer";
+extern const char RNSScreenNavigationContainerComponentName[] =
+    "RNSScreenNavigationContainer";
+extern const char RNSScreenContentWrapperComponentName[] = "RNSScreenContentWrapper";
+extern const char RNSScreenStackHeaderSubviewComponentName[] =
+    "RNSScreenStackHeaderSubview";
+
+extern const char RNSScreenStackComponentName[] = "RNSScreenStack";
+extern const char RNSScreenStackHeaderConfigComponentName[] =
+    "RNSScreenStackHeaderConfig";
+
+RNSScreenStackHeaderConfigProps::RNSScreenStackHeaderConfigProps(
+    const PropsParserContext &context,
+    const RNSScreenStackHeaderConfigProps &sourceProps,
+    const RawProps &rawProps)
+    : ViewProps(context, sourceProps, rawProps),
+      hidden(convertRawProp(context, rawProps, "hidden", sourceProps.hidden, false)) {
+  // Nothing is styled here on purpose. Setting `yogaStyle` from a props
+  // constructor does not reach this node: the yoga node holds its own copy,
+  // and the props the node ends up with are not always the ones built here.
+  // The bar is shaped in `adopt()` and taken out of the layout in `layout()`,
+  // which are the two places that work. See the header.
+}
+
+void RNSScreenStackHeaderConfigShadowNode::layout(LayoutContext layoutContext) {
+  ConcreteViewShadowNode::layout(layoutContext);
+
+  // Hidden, or with nothing to show. Both end the same way and both have to
+  // happen here rather than through the style, for the reason the props
+  // constructor gives.
+  if (!getConcreteProps().hidden && !getChildren().empty()) {
+    return;
+  }
+  auto metrics = getLayoutMetrics();
+  if (metrics.displayType == DisplayType::None) {
+    return;
+  }
+  metrics.displayType = DisplayType::None;
+  setLayoutMetrics(metrics);
+}
+
+// See the header: the content wrapper fills the screen, so the bar sits on top
+// of it until something moves it.
+void RNSScreenShadowNode::layout(LayoutContext layoutContext) {
+  ConcreteViewShadowNode::layout(layoutContext);
+
+  // The bar, and the body out from under it, together.
+  //
+  // Both here rather than the bar in the header itself, because the fallback
+  // path has no screen node at all: react-native-screens renders plain views
+  // where the native components are unavailable, nothing would move the body,
+  // and a bar given a height there would only be a taller strip painted over
+  // the content than the one already in the way.
+  RNSScreenStackHeaderConfigShadowNode *header = nullptr;
+  for (const auto &child : getChildren()) {
+    auto *candidate = const_cast<RNSScreenStackHeaderConfigShadowNode *>(
+        dynamic_cast<const RNSScreenStackHeaderConfigShadowNode *>(child.get()));
+    if (candidate == nullptr || candidate->getConcreteProps().hidden ||
+        candidate->getLayoutMetrics().displayType == DisplayType::None) {
+      continue;
+    }
+    header = candidate;
+    break;
+  }
+  if (header == nullptr) {
+    return;
+  }
+
+  auto headerMetrics = header->getLayoutMetrics();
+  const auto natural = headerMetrics.frame.size.height;
+  if (natural <= 0) {
+    return;
+  }
+  const auto barHeight = natural + 2 * kHeaderPaddingY;
+
+  headerMetrics.frame.size.height = barHeight;
+  header->ensureUnsealed();
+  header->setLayoutMetrics(headerMetrics);
+
+  // Grown after the fact, so the title keeps the position yoga gave it and is
+  // moved down by half the margin rather than relaid out. Vertical only:
+  // shifting a child sideways without reflowing it would push a centred title
+  // off centre, which is the one arrangement that works here.
+  for (const auto &child : header->getChildren()) {
+    auto *inside = const_cast<ShadowNode *>(child.get());
+    auto *layoutable = dynamic_cast<LayoutableShadowNode *>(inside);
+    if (layoutable == nullptr) {
+      continue;
+    }
+    auto metrics = layoutable->getLayoutMetrics();
+    metrics.frame.origin.y += kHeaderPaddingY;
+    inside->ensureUnsealed();
+    layoutable->setLayoutMetrics(metrics);
+  }
+
+  for (const auto &child : getChildren()) {
+    auto *body = const_cast<ShadowNode *>(child.get());
+    if (body == static_cast<ShadowNode *>(header)) {
+      continue;
+    }
+    auto *layoutable = dynamic_cast<LayoutableShadowNode *>(body);
+    if (layoutable == nullptr) {
+      continue;
+    }
+    auto metrics = layoutable->getLayoutMetrics();
+    if (metrics.displayType == DisplayType::None || metrics.frame.origin.y != 0) {
+      continue;
+    }
+    metrics.frame.origin.y = barHeight;
+    metrics.frame.size.height = std::max(0.0f, metrics.frame.size.height - barHeight);
+    body->ensureUnsealed();
+    layoutable->setLayoutMetrics(metrics);
+  }
+}
+
+void RNSScreenStackShadowNode::layout(LayoutContext layoutContext) {
+  ConcreteViewShadowNode::layout(layoutContext);
+
+  const auto &children = getChildren();
+
+
+  // The topmost screen that is not see-through. Everything below it is covered
+  // and gets hidden; a transparent modal covers nothing, so the search keeps
+  // going down past one.
+  auto topOpaque = children.size();
+  for (auto i = children.size(); i-- > 0;) {
+    const auto *screen = dynamic_cast<const RNSScreenShadowNode *>(children[i].get());
+    if (screen == nullptr || screen->getConcreteProps().seeThrough) {
+      continue;
+    }
+    topOpaque = i;
+    break;
+  }
+  if (topOpaque == children.size()) {
+    return;
+  }
+
+  for (size_t i = 0; i < topOpaque; ++i) {
+    auto *child = const_cast<ShadowNode *>(children[i].get());
+    auto *layoutable = dynamic_cast<LayoutableShadowNode *>(child);
+    if (layoutable == nullptr) {
+      continue;
+    }
+    auto metrics = layoutable->getLayoutMetrics();
+    if (metrics.displayType == DisplayType::None) {
+      continue;
+    }
+    metrics.displayType = DisplayType::None;
+    // The same pair YogaLayoutableShadowNode::layout uses to write a child's
+    // metrics: a node is sealed after its commit and has to be told before it
+    // is written to.
+    child->ensureUnsealed();
+    layoutable->setLayoutMetrics(metrics);
+  }
+}
+
+} // namespace facebook::react
+
+namespace basalt {
+
+DesktopScreensModule::DesktopScreensModule(
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+    : TurboModule(kModuleName, std::move(jsInvoker)) {
+  // Deliberately empty. See the header.
+}
+
+} // namespace basalt

package/native/core/ScreensComponent.h

@@ -0,0 +1,216 @@
+// react-native-screens, as much of it as a desktop needs.
+//
+// ## What this is for
+//
+// react-navigation's native stack renders every screen it has ever pushed and
+// relies on the platform to show one of them. The signal is `activityState` on
+// each `RNSScreen`: 0 for a screen that is behind another, 2 for the one in
+// front. With no native half, every screen is mounted and laid out at full
+// size, one painted over the other. It looks right and is not: both are in the
+// tree, both are measured, and a screen reader reads both.
+//
+// Measured before this existed, pushing Details over Home left tags 18 and 38
+// side by side in the dumped tree, both 900x700. See docs/backlog/ecosystem.md.
+//
+// ## Why `display: none` rather than a mounting peer
+//
+// The platforms react-native-screens was written for detach the inactive
+// screen's view from the container, which is a mounting-layer operation and
+// would be three implementations of it here. Yoga already has the concept:
+// `display: none` takes a subtree out of layout entirely, and every host here
+// already honours it, so an inactive screen stops being laid out and stops
+// being painted without any host learning the word "screen".
+//
+// The difference from a real detach is that the shadow node still exists, which
+// costs a node per background screen and nothing else. What it buys is that the
+// behaviour is identical on all three desktops for free.
+//
+// ## What is deliberately not here
+//
+// The header. `RNSScreenStackHeaderConfig` carries a title, a back button and a
+// tint, and drawing it means a real toolkit header per platform rather than a
+// prop translation. It is registered as a plain view so that it mounts and
+// takes no space, which is what it already did. An app that wants a title bar
+// today draws its own; see docs/backlog/ecosystem.md.
+
+#pragma once
+
+#include <ReactCommon/TurboModule.h>
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/components/view/ViewEventEmitter.h>
+#include <react/renderer/components/view/ViewProps.h>
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+#include <react/renderer/core/LayoutContext.h>
+
+namespace facebook::react {
+
+extern const char RNSScreenComponentName[];
+
+class RNSScreenProps final : public ViewProps {
+ public:
+  RNSScreenProps() = default;
+  RNSScreenProps(const PropsParserContext &context,
+                 const RNSScreenProps &sourceProps,
+                 const RawProps &rawProps);
+
+  // 0 inactive, 1 transitioning, 2 active, and -1 for "the library is not
+  // managing this one", which is its own default and has to stay visible.
+  float activityState{-1.0f};
+
+  // Whether the screen beneath this one shows through it. True for the
+  // `transparentModal` presentations and false for everything else, which is
+  // what decides how far down the stack hides. Parsed from `stackPresentation`
+  // rather than kept as the string, because that is the only question asked.
+  bool seeThrough{false};
+};
+
+// The screen, which also has to get its content out from under the header.
+//
+// react-native-screens gives the content wrapper `StyleSheet.absoluteFill`, so
+// it covers the whole screen and the header, which is an ordinary in-flow
+// child, is painted on top of it. That is right on a platform whose navigation
+// bar floats; here it means the first 56 points of every screen are behind the
+// bar.
+//
+// The screen is the only node that can see both, so it moves the content down
+// by the header's height after layout. `adopt()` cannot do it instead: it runs
+// before the children are attached, measured by a probe that saw zero of them.
+class RNSScreenShadowNode final
+    : public ConcreteViewShadowNode<RNSScreenComponentName, RNSScreenProps,
+                                    ViewEventEmitter> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+
+  void layout(LayoutContext layoutContext) override;
+};
+using RNSScreenComponentDescriptor = ConcreteComponentDescriptor<RNSScreenShadowNode>;
+
+// The containers. Each is a plain view that holds screens, so ViewProps parses
+// all of it and the only thing each needs of its own is a name. A name Fabric
+// does not know becomes UnimplementedNativeView, which mounts but carries none
+// of the props, so registering them is what makes the stack lay out at all.
+#define BASALT_SCREENS_VIEW(Symbol)                                           \
+  extern const char Symbol##ComponentName[];                                  \
+  using Symbol##ShadowNode =                                                  \
+      ConcreteViewShadowNode<Symbol##ComponentName, ViewProps, ViewEventEmitter>; \
+  using Symbol##ComponentDescriptor = ConcreteComponentDescriptor<Symbol##ShadowNode>;
+
+BASALT_SCREENS_VIEW(RNSScreenContainer)
+BASALT_SCREENS_VIEW(RNSScreenNavigationContainer)
+BASALT_SCREENS_VIEW(RNSScreenContentWrapper)
+BASALT_SCREENS_VIEW(RNSScreenStackHeaderSubview)
+
+#undef BASALT_SCREENS_VIEW
+
+extern const char RNSScreenStackHeaderConfigComponentName[];
+
+/**
+ * What a header puts around its content.
+ *
+ * A bar is its title plus a margin rather than a fixed height, which lands
+ * within a few points of the 56 every toolkit uses and centres a one-line
+ * title without needing to know how tall it is.
+ *
+ * Applied by the screen, not by the header, because the screen also moves the
+ * body down out of the way and the two have to happen together or not at all.
+ * See RNSScreenShadowNode::layout.
+ */
+inline constexpr float kHeaderPaddingY = 18.0f;
+
+// The header bar.
+//
+// On iOS and Android this component configures a navigation bar that the
+// platform draws, and most of its props describe that bar. Here there is no
+// such bar, and the useful half of it arrives as views: react-navigation's
+// native stack takes its non-iOS branch on every desktop, which renders the
+// title, the back button and anything custom as `RNSScreenStackHeaderSubview`
+// children rather than as strings for a toolbar to draw.
+//
+// So this is a row that lays those children out, and the props it reads are the
+// ones that describe the row rather than the ones that describe UIKit.
+//
+// `title` as a plain string is the part that does not arrive as a view, and is
+// not drawn: react-navigation only renders it as a `<Text>` when the title is
+// centred or supplied as a component. See the navigation page in the docs.
+class RNSScreenStackHeaderConfigProps final : public ViewProps {
+ public:
+  RNSScreenStackHeaderConfigProps() = default;
+  RNSScreenStackHeaderConfigProps(const PropsParserContext &context,
+                                  const RNSScreenStackHeaderConfigProps &sourceProps,
+                                  const RawProps &rawProps);
+
+  bool hidden{false};
+};
+
+// A header with nothing in it takes no space.
+//
+// react-navigation renders the title as a view only when it is centred or
+// supplied as a component; a plain left-aligned string goes to the `title`
+// prop, for a toolbar that does not exist here, and the config ends up with no
+// children at all. Reserving 56 points for that would replace today's missing
+// header with an empty grey bar, which is worse: at least nothing looks
+// deliberate.
+//
+// Decided after layout because that is the first point at which the children
+// are attached. `adopt()` runs before they are, measured rather than assumed.
+class RNSScreenStackHeaderConfigShadowNode final
+    : public ConcreteViewShadowNode<RNSScreenStackHeaderConfigComponentName,
+                                    RNSScreenStackHeaderConfigProps,
+                                    ViewEventEmitter> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+
+  void layout(LayoutContext layoutContext) override;
+};
+using RNSScreenStackHeaderConfigComponentDescriptor =
+    ConcreteComponentDescriptor<RNSScreenStackHeaderConfigShadowNode>;
+
+extern const char RNSScreenStackComponentName[];
+
+// The stack, which shows one screen and covers the rest.
+//
+// A native stack renders every screen it has pushed and expects the platform to
+// show the top one. On iOS that is UINavigationController; `activityState` is
+// not the signal, and measuring it is what established that: react-native-screens
+// throws `activityState cannot be decreased in NativeStack`, and every screen in
+// a pushed stack reports 2, the covered ones included.
+//
+// So the stack does it, after layout, by giving every screen below the topmost
+// opaque one `DisplayType::None`. All three mounting managers already hide a
+// view on exactly that, so this is one implementation rather than three, and a
+// hidden widget is out of the accessibility tree on each of them for free.
+//
+// What this does not do is skip the layout. Yoga has already measured the
+// covered screens by the time `layout()` can see which is on top, and the only
+// way to get in front of that would be for a screen to know its own position in
+// the stack, which it does not. The cost is measuring a subtree that is not
+// shown; the thing that was actually wrong, two screens mounted and both
+// reaching accessibility, is fixed.
+class RNSScreenStackShadowNode final
+    : public ConcreteViewShadowNode<RNSScreenStackComponentName, ViewProps,
+                                    ViewEventEmitter> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+
+  void layout(LayoutContext layoutContext) override;
+};
+
+
+using RNSScreenStackComponentDescriptor =
+    ConcreteComponentDescriptor<RNSScreenStackShadowNode>;
+
+} // namespace facebook::react
+
+namespace basalt {
+
+// `RNSModule`, whose TypeScript spec is `interface Spec extends TurboModule {}`:
+// no methods at all. The library only asks whether it is there, and answering
+// null is what produced the warning in every log. Nothing calls anything on it.
+class DesktopScreensModule : public facebook::react::TurboModule {
+ public:
+  static constexpr auto kModuleName = "RNSModule";
+
+  explicit DesktopScreensModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+};
+
+} // namespace basalt

package/native/core/ScrollBounds.cpp

@@ -15,6 +15,14 @@ ScrollRange scrollRangeFor(double containerLength,
   return range;
 }
 
+ScrollAxisInsets centeringInsets(double containerLength, double contentLength) {
+  const double slack = containerLength - contentLength;
+  if (slack <= 0.0) {
+    return {};
+  }
+  return ScrollAxisInsets{.leading = slack / 2.0, .trailing = slack / 2.0};
+}
+
 double clampScrollOffset(double offset,
                          double containerLength,
                          double contentLength,

package/native/core/ScrollBounds.h

@@ -54,6 +54,20 @@ ScrollRange scrollRangeFor(double containerLength,
                            double contentLength,
                            ScrollAxisInsets insets = {});
 
+// `centerContent`: the inset that centres content smaller than its container.
+//
+// Half the slack at each end, and nothing at all once the content is longer
+// than the container -- a list that can scroll has nothing to centre.
+//
+// An inset rather than a position, which is not a trick: with half the slack at
+// each end the range above collapses to the single offset `-slack/2`, so the
+// clamp every host already runs on every mutation puts the content in the
+// middle and keeps it there. That is also how iOS does it --
+// `RCTEnhancedScrollView`'s `centerContentIfNeeded` assigns a `contentInset` of
+// exactly these numbers -- and why `centerContent` overrides the app's own
+// `contentInset` there and here: the two are the same channel.
+ScrollAxisInsets centeringInsets(double containerLength, double contentLength);
+
 // An offset brought inside that range.
 //
 // The one place the three hosts agreed already, and now the one place it is

package/native/core/ScrollIndicator.h

@@ -38,6 +38,73 @@ inline constexpr double kScrollIndicatorInset = 2.0;
 // Below this a thumb stops reading as a position and starts reading as a dot.
 inline constexpr double kScrollIndicatorMinimumLength = 24.0;
 
+// `indicatorStyle`, as React Native's three values.
+//
+// `UIScrollViewIndicatorStyleDefault` is "black with a white border", `.black`
+// is black alone, and `.white` is the one a list over dark content asks for,
+// where a black thumb is invisible. So the three are two fills and one border,
+// and the border is what tells `default` from `black`: it is a hairline of
+// white around the pill, which is what keeps the default thumb visible over
+// dark and light content both.
+enum class ScrollIndicatorStyle {
+  Default,
+  Black,
+  White,
+};
+
+// Straight sRGB with alpha, which all three toolkits take in that form.
+struct ScrollIndicatorColour {
+  float red{0.0F};
+  float green{0.0F};
+  float blue{0.0F};
+  float alpha{0.0F};
+};
+
+// Translucent, so the thumb reads over whatever it sits on rather than hiding
+// it. One number for both colours: a white thumb that was more opaque than the
+// black one would read as a different control.
+inline constexpr float kScrollIndicatorAlpha = 0.35F;
+
+// `inline` rather than a function in the .cpp, and not for speed: the three
+// view layers link no core at all -- each is built and tested with nothing but
+// its toolkit, which is what lets the Win32 suite run on a box with a compiler
+// and the SDK -- so anything they take from here has to be a header. The view
+// layers need this one to spell their own default thumb, and the managers need
+// it to answer the prop.
+inline ScrollIndicatorColour scrollIndicatorColourFor(ScrollIndicatorStyle style) {
+  if (style == ScrollIndicatorStyle::White) {
+    return ScrollIndicatorColour{
+        .red = 1.0F, .green = 1.0F, .blue = 1.0F, .alpha = kScrollIndicatorAlpha};
+  }
+  // `Default` and `Black` share a fill and differ by the border below, which
+  // is exactly how iOS's two differ.
+  return ScrollIndicatorColour{
+      .red = 0.0F, .green = 0.0F, .blue = 0.0F, .alpha = kScrollIndicatorAlpha};
+}
+
+// A hairline, which is what a border around a six-point pill can be without
+// becoming the thumb. One point rather than a fraction: two of the three hosts
+// stroke in logical points and a half-point line lands differently in each.
+inline constexpr double kScrollIndicatorBorderWidth = 1.0;
+
+// Rather more opaque than the fill, for the one job it has: the fill is a wash
+// that lets the content through, and an outline as faint as that would not
+// separate a black thumb from black content behind it.
+inline constexpr float kScrollIndicatorBorderAlpha = 0.6F;
+
+// The border around the thumb, or nothing for the two styles that have none.
+//
+// Only `Default` has one. `black` and `white` are the styles an app chooses
+// *because* it knows what is behind the thumb, and iOS draws neither with an
+// outline; adding one to either would be this platform inventing a look.
+inline ScrollIndicatorColour scrollIndicatorBorderColourFor(ScrollIndicatorStyle style) {
+  if (style == ScrollIndicatorStyle::Default) {
+    return ScrollIndicatorColour{
+        .red = 1.0F, .green = 1.0F, .blue = 1.0F, .alpha = kScrollIndicatorBorderAlpha};
+  }
+  return ScrollIndicatorColour{};
+}
+
 struct ScrollIndicator {
   // False when everything fits: a scrollbar for content that cannot scroll is
   // noise, and every list shorter than its container would grow one.

package/native/core/ScrollMomentum.cpp

@@ -62,6 +62,30 @@ bool ScrollMomentum::advance(double seconds, double &dx, double &dy) {
   return true;
 }
 
+double scrollMomentumDistance(double velocity, double decelerationRate) {
+  const double speed = std::abs(velocity);
+  if (speed < kStopSpeed) {
+    // A release rather than a fling, which is the same threshold `start`
+    // refuses at: nothing coasts from here.
+    return 0.0;
+  }
+  const double rate = std::clamp(decelerationRate, 0.5, 0.9999);
+  const double decay = std::log(rate);
+  if (decay >= 0.0) {
+    return 0.0;
+  }
+
+  // Velocity is in pixels per second and the rate is a factor per millisecond,
+  // which is the awkwardness React Native's own prop carries. So the integral
+  // is over milliseconds and the velocity is divided by a thousand to match:
+  //
+  //   distance = (v/1000) * integral of rate^t dt, from 0 to the moment the
+  //   speed falls to kStopSpeed, which is (rate^T - 1) / ln(rate) with
+  //   rate^T = kStopSpeed / |v|.
+  const double travelled = (speed / 1000.0) * ((kStopSpeed / speed) - 1.0) / decay;
+  return velocity < 0.0 ? -travelled : travelled;
+}
+
 void ScrollMomentum::stop() {
   running_ = false;
   velocityX_ = 0;