basalt-appkit 0.0.0-rc5 → 0.2.0

package/native/appkit/RnAppKitView.h

@@ -26,6 +26,10 @@
 
 #ifdef __OBJC__
 #import <Cocoa/Cocoa.h>
+// For CALayer, which `boxShadow` is made of: Cocoa declares the view and
+// QuartzCore the layers under it.
+#import <CoreImage/CoreImage.h>
+#import <QuartzCore/QuartzCore.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -196,6 +200,43 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 // fit.
 - (void)setRnImage:(nullable CGImageRef)image fit:(RnAppKitImageFit)fit;
 
+// The frames of an animated image, their delays, and how many times round.
+//
+// `frames` holds CGImageRefs and `delaysMs` the file's own delays, one per
+// frame, unclamped: core/ImageAnimation.h applies the clamp, because that rule
+// is the same on every host. `loopCount` is zero for forever. Fewer than two
+// frames, or nil, is a still image and clears any animation.
+//
+// The view shows frame zero immediately and schedules the rest. Passing the
+// same `frames` array again is a no-op, which is how a layout-only mutation
+// avoids restarting the animation; AppKitImageLoader keeps one array per URI
+// for exactly that.
+- (void)setRnImageFrames:(nullable NSArray *)frames
+                delaysMs:(nullable NSArray<NSNumber *> *)delaysMs
+               loopCount:(NSUInteger)loopCount;
+
+// Starts the timer that shows the rest of the frames, if one is not running.
+//
+// Separate from `setRnImageFrames:` so that nothing animates by itself: the
+// mounting manager starts it because the view is in an app, and the suite never
+// does, which keeps a test about frames deterministic. The GTK view is split
+// the same way, where it matters more -- rendering a widget there spins the
+// main loop, and a self-driven animation would be several frames further on
+// than the test left it.
+- (void)rnStartImageAnimation;
+
+// Moves the animation on by `milliseconds` and shows the frame that lands on,
+// answering with how long until the next one, or zero when nothing more is due.
+//
+// The elapsed time is an argument rather than a clock read inside: the host's
+// timer passes the delay it waited, and the suite passes whatever it likes,
+// which is what makes "a hundred and fifty milliseconds later" something a test
+// can say without sleeping.
+- (double)rnAdvanceImageAnimationBy:(double)milliseconds;
+
+// Which frame is showing, zero for a still image.
+@property(nonatomic, readonly) NSUInteger rnImageFrameIndex;
+
 // `tintColor`: recolours the image, keeping its alpha, so one silhouette asset
 // can be drawn in any colour. Pass nil to clear.
 //
@@ -203,6 +244,15 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 // from a loader, and either can land first.
 - (void)setRnImageTint:(nullable NSColor *)tint;
 
+// `blurRadius`: blurs the image and not the view, which is what the prop means
+// -- a blurred photograph behind sharp text is the usual reason to ask for it.
+// Zero or negative is no blur.
+//
+// The radius is a distance in this view's own coordinates rather than in the
+// image's pixels, so the same number is the same picture here as on the GTK
+// side. Also separate from the image for the reason the tint is.
+- (void)setRnImageBlur:(CGFloat)radius;
+
 // The paragraph this view draws, or nil for a view that draws none.
 //
 // A view either paints a layer or draws text; nothing here does both, because
@@ -212,6 +262,43 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 // both the mounting manager and the measurement seam go through that, so the
 // size a view draws at is the size Yoga was told.
 - (void)setRnTextLayout:(nullable id)layout;
+
+// --- Selecting that text ------------------------------------------------------
+//
+// `<Text selectable>`, which `userSelect` also arrives in. The same four
+// questions the GTK side answers in C, in the same order and with the same
+// units: whether this paragraph may be selected, where a point lands in its
+// text, what range is selected, and what that range says. The state machine
+// above them is core/TextSelection.h, shared by all three hosts.
+//
+// Indices are UTF-16 code units, which is what `NSAttributedString` counts;
+// the GTK side counts UTF-8 bytes, and core/TextSelection.h says why the two
+// never have to agree.
+- (void)setRnTextSelectable:(BOOL)selectable;
+- (BOOL)rnTextSelectable;
+
+// -1 when this view draws no paragraph. `point` is in the view's own
+// coordinates.
+- (NSInteger)rnTextIndexAtPoint:(CGPoint)point;
+
+// How far down its box this view's paragraph is drawn, which is zero for every
+// view that draws no text and for every paragraph that says nothing about
+// `textAlignVertical`.
+//
+// The inline views inside a paragraph are moved by it. React Native measures an
+// attachment against the content box and places it from the top --
+// `ParagraphShadowNode::layout` adds the content insets and nothing else -- so
+// it knows nothing about a box taller than its text, which is what
+// `textAlignVertical` is about. Without this a marker inside a bottom-aligned
+// sentence stayed at the top while the words went to the bottom.
+- (CGFloat)rnTextVerticalOffset;
+
+- (void)setRnTextSelectionStart:(NSInteger)start length:(NSInteger)length;
+- (NSInteger)rnTextSelectionStart;
+- (NSInteger)rnTextSelectionLength;
+
+// The selected text, or nil when nothing is selected.
+- (nullable NSString *)rnSelectedText;
 - (void)setRnClipsChildren:(BOOL)clips;
 
 // `zIndex`. Reorders painting and hit testing, and never the child list --
@@ -285,6 +372,217 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 - (void)setRnBorderWidths:(nullable const CGFloat *)widths
                    colors:(nullable const CGFloat *)colors;
 
+// One colour stop of a gradient: an offset from 0 to 1 along the gradient line
+// and the colour there, as RGBA components.
+typedef struct {
+  CGFloat offset;
+  CGFloat color[4];
+} RnAppKitGradientStop;
+
+// Which kind of gradient a record is. CSS's `background-image` is one list that
+// can hold both, and the first in it is the one on top, so they cannot be two
+// lists here without losing the order between them.
+typedef NS_ENUM(NSInteger, RnAppKitGradientKind) {
+  RnAppKitGradientKindLinear,
+  RnAppKitGradientKindRadial,
+};
+
+// One `backgroundImage` gradient, already resolved against this view's size: a
+// linear one's two end points, or a radial one's centre and two radii, in this
+// view's own coordinates.
+//
+// Resolved rather than described, because the resolution is CSS's and is shared
+// with the GTK host in core/Gradients.h -- the angle or the ending shape, the box
+// size and the stop fixup all go into these numbers and the offsets. This layer
+// draws what it is given. The stops are borrowed for the duration of the call.
+typedef struct {
+  RnAppKitGradientKind kind;
+  // Linear only: the ends of the gradient line.
+  CGPoint start;
+  CGPoint end;
+  // Radial only: the centre of the ending shape and its two radii. A circle is
+  // an ellipse whose radii are equal, which is what CSS makes of one.
+  CGPoint center;
+  CGFloat radiusX;
+  CGFloat radiusY;
+  // Where the image goes and how it tiles, from `backgroundSize`,
+  // `backgroundPosition` and `backgroundRepeat`, resolved in
+  // core/BackgroundLayers.h: `area` is the rectangle the gradient fills, in this
+  // view's coordinates, and `tile` is what it repeats in -- the same rectangle
+  // for `repeat`, wider for `space`, and the painting area's extent on an axis
+  // that does not repeat, so one step covers it.
+  //
+  // The gradient's own geometry above is resolved against `area`'s size and
+  // offset to its origin, so this layer draws rather than positions.
+  CGRect area;
+  CGRect tile;
+  bool repeats;
+  const RnAppKitGradientStop *stops;
+  NSInteger stopCount;
+} RnAppKitGradient;
+
+// `backgroundImage`. Replaces whatever was there; pass NULL or 0 for none.
+//
+// Drawn above the background colour, which is a layer property and therefore
+// below anything `drawRect:` paints, and below the image and the text, which is
+// where CSS puts a background image. First in the list is on top, so they are
+// drawn back to front.
+- (void)setRnGradients:(nullable const RnAppKitGradient *)gradients count:(NSInteger)count;
+
+// How many are set, for the tests and the tree dump.
+@property(nonatomic, readonly) NSInteger rnGradientCount;
+
+// One CSS box shadow, in React Native's own terms: `BoxShadow` carries exactly
+// these fields. The colour is RGBA components in that order, as the border
+// colours arrive, so this header stays free of NSColor for the same reason the
+// rest of it is.
+typedef struct {
+  CGFloat dx;
+  CGFloat dy;
+  CGFloat blur;
+  CGFloat spread;
+  CGFloat color[4];
+  bool inset;
+} RnAppKitBoxShadow;
+
+// `boxShadow`. Replaces whatever was there; pass NULL or 0 for none.
+//
+// Order is CSS's: the first shadow in the list is the one on top. Each becomes a
+// CALayer of its own with a shadow path and a mask, which is the only way to
+// paint outside a view -- `drawRect:` is clipped to the bounds and an outset
+// shadow is by definition outside them. It is also what React Native's own iOS
+// half does, so a shadow lands in the same place on both.
+- (void)setRnBoxShadows:(nullable const RnAppKitBoxShadow *)shadows count:(NSInteger)count;
+
+// How many are set, for the tests and the tree dump.
+@property(nonatomic, readonly) NSInteger rnBoxShadowCount;
+
+// The layers those shadows became, bottom to top, for the tests: each one's
+// `shadowPath`, `shadowRadius` and `mask` are the whole feature, and they are
+// what macOS composites rather than anything this code draws.
+@property(nonatomic, readonly) NSArray<CALayer *> *rnBoxShadowLayers;
+
+// `filter`, already resolved: the colour matrix the list comes to, one blur
+// radius and one opacity. See core/Filters.h, which is shared with the GTK host
+// and does the arithmetic the Filter Effects spec specifies.
+//
+// `matrix` is row-major in R, G, B, A order and `offset` is added after it, both
+// in straight colour, which is what CIColorMatrix takes. `blurRadius` is CSS's
+// radius, twice the gaussian's sigma. `opacity` is 1 when the list has no
+// `opacity()`.
+// One `dropShadow()` from a filter list: a shadow of the subtree's alpha rather
+// than of its box, which is what makes it a filter and not a box shadow.
+//
+// `standardDeviation` is the gaussian's, which is what React Native parses and
+// what `CALayer.shadowRadius` takes, so it crosses unchanged. The colour is RGBA
+// components, as the border and shadow colours are.
+typedef struct {
+  CGFloat dx;
+  CGFloat dy;
+  CGFloat standardDeviation;
+  CGFloat color[4];
+} RnAppKitFilterShadow;
+
+typedef struct {
+  bool hasMatrix;
+  CGFloat matrix[16];
+  CGFloat offset[4];
+  CGFloat blurRadius;
+  CGFloat opacity;
+  // Borrowed for the duration of the call, in the order they were written: the
+  // first is the one nearest the content, which CSS applying a filter list
+  // left to right is what makes true. A CALayer carries one shadow, so the
+  // first is the view's own layer's -- cast from the content's alpha -- and
+  // each of the rest is a layer of its own cast from the view's box. The
+  // difference shows only on content with holes in it, and
+  // backlog/platform-macos.md records it.
+  const RnAppKitFilterShadow *shadows;
+  NSInteger shadowCount;
+} RnAppKitFilters;
+
+// `filter`. Pass NULL for none.
+//
+// Applies to this view and everything inside it, which is what CSS does.
+// `CALayer.filters` is the mechanism and is the reason this is one of the few
+// props macOS does better than React Native's own iOS half: Core Image filters
+// on a layer are public API here and private there, so iOS builds a SwiftUI
+// wrapper and a multiply-blend layer to approximate what this sets directly.
+- (void)setRnFilters:(nullable const RnAppKitFilters *)filters;
+
+// The Core Image filters the layer is carrying, for the tests: a shadow or a
+// filter is composited by Core Animation and `renderInContext:` draws neither,
+// so what each filter was given is the observable half here. The GTK side has
+// the render tree and checks a pixel.
+@property(nonatomic, readonly) NSArray<CIFilter *> *rnFilters;
+
+// The drop shadow the filter list asked for, as the layer properties it became,
+// or all zeroes when there is none. Public for the tests, for the reason
+// `rnFilters` is: Core Animation composites a shadow and `renderInContext:` does
+// not draw one.
+@property(nonatomic, readonly) RnAppKitFilterShadow rnFilterShadow;
+
+// `hitSlop`: how far outside its own box this view answers a press, in the order
+// top, right, bottom, left -- the order CSS names edges and the order the border
+// widths arrive in. Null or all zeroes is no slop.
+//
+// Positive values grow the target. A 44pt row with a 20pt icon in it is the
+// reason the prop exists: the icon is what the eye aims at and the finger, or on
+// a desktop a hurried cursor, misses it.
+//
+// It changes hit testing and nothing else: the view is drawn in its own frame,
+// and `RnAppKitHitTest` is the only reader. That also means it applies to hover
+// and to a drop as well as to a press, which is what iOS does, those all going
+// through one hit test.
+- (void)setRnHitSlop:(nullable const CGFloat *)insets;
+
+// The box a press has to land in: the bounds, grown by `hitSlop`. Read by
+// `RnAppKitHitTest` and by the tests, which is why it is here rather than in the
+// implementation.
+@property(nonatomic, readonly) NSRect rnHitArea;
+
+// `borderStyle`, for the two values that are not solid.
+typedef NS_ENUM(NSInteger, RnAppKitBorderStyle) {
+  RnAppKitBorderStyleSolid = 0,
+  RnAppKitBorderStyleDotted,
+  RnAppKitBorderStyleDashed,
+};
+
+// A dotted or dashed border is drawn differently from a solid one: one stroked
+// path around the view's own rounded rectangle, with a dash pattern scaled to
+// the border width the way every browser does it, since a fixed pattern looks
+// like a hairline on a thick border and like a solid line on a thin one.
+//
+// It replaces the four-edge fill rather than joining it, or the outline would be
+// painted twice and the dashes would sit on a solid line.
+//
+// One style for the whole outline rather than one per side, which is the limit of
+// this and is the limit on the other hosts for the same reason: a stroked path
+// carries one dash pattern, and React Native's per-side `borderStyles` would need
+// four paths with the corners divided between them. The first side that asks for
+// something other than solid decides the outline, and the backlog records that.
+- (void)setRnBorderStyle:(RnAppKitBorderStyle)style;
+
+// `outlineWidth`, `outlineColor`, `outlineOffset` and `outlineStyle`.
+//
+// CSS's outline, which is not a border: drawn *outside* the box, no layout space,
+// and `offset` away from the border edge. A focus ring is what it is for.
+//
+// A layer rather than a `drawRect:`, for the reason an outset box shadow is one:
+// `drawRect:` is clipped to the bounds and this is outside them. It follows the
+// same placement rule as the shadows -- inside the view, or in the parent when
+// the view clips its own layer -- so the two props behave alike.
+//
+// The colour is RGBA components, as the border colours arrive. A zero width is no
+// outline.
+- (void)setRnOutlineWidth:(CGFloat)width
+                   offset:(CGFloat)offset
+                    color:(nullable const CGFloat *)color
+                    style:(RnAppKitBorderStyle)style;
+
+// The layer that outline became, for the tests: a stroked shape outside the box,
+// which `renderInContext:` will not draw and a `drawRect:` bitmap cannot see.
+@property(nonatomic, readonly, nullable) CAShapeLayer *rnOutlineLayer;
+
 // Fabric's Insert and Remove carry an index into the parent's child list, so
 // that list has to stay in mutation order.
 - (void)insertRnChild:(RnAppKitView *)child atIndex:(NSInteger)index;
@@ -324,12 +622,70 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 // Accessible states. Each is a tri-state: unset leaves AppKit's default alone,
 // which is not the same as setting it false.
 
+// accessibilityValue: a range and a position in it, or a text form that reads
+// better than the number. nil for a part the app did not give, which is how an
+// element says it has none. See the definition: this shares AppKit's one
+// `accessibilityValue` with the checked state, and an explicit value wins.
+- (void)setRnAccessibleValueMin:(nullable NSNumber *)min
+                            max:(nullable NSNumber *)max
+                            now:(nullable NSNumber *)now
+                           text:(nullable NSString *)text;
+
 - (void)setRnAccessibleStateDisabled:(RnAppKitAccessibleFlag)disabled
                              checked:(RnAppKitAccessibleFlag)checked
                             selected:(RnAppKitAccessibleFlag)selected
                             expanded:(RnAppKitAccessibleFlag)expanded
                                 busy:(RnAppKitAccessibleFlag)busy;
 
+// `accessibilityLabelledBy`, already resolved: the views whose text names this
+// one. Pass nil or an empty array to take the relation off again.
+//
+// The prop names other views by their `nativeID`, and the resolution -- and
+// above all *when* to resolve, Fabric mounting a field before the label that
+// follows it -- is shared with the GTK host in core/LabelRegistry.h. This layer
+// is handed the answer.
+//
+// **AppKit takes one.** `accessibilityTitleUIElement` is a single element where
+// the prop is a list and GTK's relation is a list, so the first is used and the
+// rest are kept only for the tree dump, which reports what was resolved on both
+// hosts. backlog/accessibility.md records that.
+- (void)setRnLabelledBy:(nullable NSArray<RnAppKitView *> *)labels;
+
+// `experimental_accessibilityOrder`, resolved: the children this view wants a
+// screen reader to read, in that order. Sets `accessibilityChildren`, which is
+// what VoiceOver walks in place of the view hierarchy.
+- (void)setRnAccessibilityOrder:(nullable NSArray<RnAppKitView *> *)children;
+
+// The text of this view and everything inside it, as a screen reader would read
+// it: each paragraph's string in tree order, separated by single spaces.
+//
+// Here for `accessibilityLiveRegion`, which announces a status message when it
+// changes and so needs to know what the message currently says. An accessible
+// label stands in for the text where one was set, which the mounting manager
+// decides before calling this, as the GTK host does.
+@property(nonatomic, readonly) NSString *rnCollectedText;
+
+// The text this view draws itself, or nil: the paragraph it holds, and nothing
+// from its children. The recursive half of `rnCollectedText` reads it from each
+// view it walks, which is why it is here rather than in the implementation.
+@property(nonatomic, readonly, nullable) NSString *rnOwnText;
+
+// Reads `text` out to VoiceOver now, as `accessibilityLiveRegion` asks. Not a
+// property: AppKit posts an announcement, and whether anybody is listening is
+// VoiceOver's business.
+//
+// `assertive` asks to interrupt what is being read; polite waits for a gap,
+// which is what the two values of the prop mean.
+//
+// The announcement is also remembered, which is the only way to see that it
+// happened: nothing in an automated run is running VoiceOver, so
+// `rnLastAnnouncement` is what the tests read. Deliberately not in the tree dump
+// -- an announcement is an event and the dump is state -- and the host logs it.
+- (void)rnAnnounce:(NSString *)text assertive:(BOOL)assertive;
+
+// The last text this view announced, or nil.
+@property(nonatomic, readonly, nullable) NSString *rnLastAnnouncement;
+
 // Hidden from assistive technology, for accessible={false} and
 // accessibilityElementsHidden.
 - (void)setRnAccessibleHidden:(BOOL)hidden;
@@ -340,6 +696,120 @@ typedef NS_ENUM(NSInteger, RnAppKitImageFit) {
 // same idea. Stored and never drawn.
 @property(nonatomic, copy, nullable) NSString *rnNativeId;
 
+// The app's `testID`, which is not `nativeID`: one is how an app names a view
+// to itself, the other is how something driving the app from outside finds it.
+// Setting it sets `accessibilityIdentifier`, which is what XCTest, Appium and
+// the Accessibility Inspector all look for, and it is printed in the tree dump
+// the way React Native spelled it.
+@property(nonatomic, copy, nullable) NSString *rnTestId;
+
+// `accessibilityViewIsModal`: a screen reader should stay inside this view
+// rather than reading what is behind it. Sets AppKit's `accessibilityModal`,
+// which is the same idea as ARIA's `aria-modal` and UIA's `IsDialog`.
+@property(nonatomic, assign) BOOL rnAccessibleModal;
+
+// `writingDirection`, for the tree dump: "ltr", "rtl", "natural", or nil when
+// the app asked for nothing. The direction itself is in the paragraph style the
+// layout carries; this is so the two hosts' dumps compare line by line.
+@property(nonatomic, copy, nullable) NSString *rnWritingDirection;
+
+// The edge the paragraph's text sits against, resolved: @"left", @"center",
+// @"right", @"justified", or nil for a view that is not a paragraph. From
+// core/TextAlignments.h, so the three hosts print the same word for the same
+// answer -- `textAlign: 'end'` is one word and two edges.
+@property(nonatomic, copy, nullable) NSString *rnTextAlign;
+
+// `textAlignVertical`, for the tree dump: @"auto", @"top", @"center",
+// @"bottom", or nil when the app said nothing. The prop rather than the offset,
+// which core/TextAlignments.h argues.
+@property(nonatomic, copy, nullable) NSString *rnTextVerticalAlign;
+
+// Where the paragraph's box ends and its text begins: padding and border,
+// which Fabric adds up into `layoutMetrics.contentInsets`.
+//
+// A <Text> may carry padding of its own, and React Native's own LogBox does:
+// its message is a `<Text style={{paddingHorizontal: 12}}>` while the heading
+// above it is a padded <View> around one, so the two lined up on a phone and
+// did not here. Yoga lays the box out with the padding either way; what was
+// missing is that the paragraph was drawn at the box's corner rather than at
+// the content's.
+//
+// Everything that reads a point against the text uses it: the draw, the
+// selection highlight that is drawn with it, the vertical alignment, and
+// `rnTextIndexAtPoint:`. React Native offsets an inline view's frame by the
+// same insets in `ParagraphShadowNode::layout`, so a paragraph drawn at the
+// corner also disagreed with the views inside it.
+@property(nonatomic) NSEdgeInsets rnTextInset;
+
+// What this scroll view's snapping is set to, as core/ScrollSnap.h formats it:
+// a fragment the tree dump prints verbatim, or nil for a view that does not
+// snap. Pushed in by the scroll manager, which is where the props are read.
+@property(nonatomic, copy, nullable) NSString *rnScrollSnap;
+
+// `spellCheck` and `autoCorrect`, for the tree dump: @"on", @"off" or nil for a
+// field that said nothing, which is the third state rather than a default. What
+// this host does with them is two properties on the NSTextView a field is or
+// borrows; see AppKitTextPeer.h.
+@property(nonatomic, copy, nullable) NSString *rnSpellCheck;
+@property(nonatomic, copy, nullable) NSString *rnAutoCorrect;
+
+// `autoCapitalize` and `keyboardType`, for the tree dump, as React Native
+// spells them. **This host acts on neither**, and says so rather than
+// pretending: macOS has no per-field automatic capitalisation
+// (`NSSpellChecker`'s is the person's system setting) and no software keyboard
+// to choose a layout for. GTK turns both into input hints and an input
+// purpose, so printing the same words is what keeps the two dumps comparable
+// and puts the difference in the support page, where it belongs.
+@property(nonatomic, copy, nullable) NSString *rnAutoCapitalize;
+@property(nonatomic, copy, nullable) NSString *rnKeyboardType;
+
+// `caretHidden` and `contextMenuHidden`, for the tree dump. What this host
+// *does* with them is a clear insertion point and a peer that refuses to build
+// a menu; see AppKitTextPeer.h, which also records the half of the second one a
+// single-line field cannot answer. Printed because each is the absence of
+// something -- a blink, a menu -- so nothing else can see that they arrived.
+@property(nonatomic, assign) BOOL rnCaretHidden;
+@property(nonatomic, assign) BOOL rnContextMenuHidden;
+
+// The `cursor` style property, as the CSS keyword React Native uses: "pointer",
+// "text", "grab", "ns-resize" and the rest. Nil or empty leaves the cursor to
+// whatever encloses this view, which is what `cursor: 'auto'` means.
+//
+// A keyword rather than an NSCursor because the name is what crosses the seam
+// from the mounting manager, shared with the GTK host through
+// core/CursorNames.h, and because macOS has no cursor for some of them: the
+// mapping and its holes belong on this side. See `rnResolvedCursor`.
+- (void)setRnCursorName:(nullable NSString *)name;
+
+// The NSCursor that name resolves to, or nil for a keyword macOS has no cursor
+// for -- "wait", "help", "move", "progress", "cell", "all-scroll". Nil means
+// this view installs no cursor rect at all, so the cursor is inherited rather
+// than forced back to an arrow.
+//
+// Public for the tests, which assert the mapping, and read by nothing else: the
+// cursor itself is applied through `resetCursorRects`, as AppKit expects.
+@property(nonatomic, readonly, nullable) NSCursor *rnResolvedCursor;
+
+// `mixBlendMode`, as the CSS keyword, shared with the GTK host through
+// core/BlendModes.h: "multiply", "screen", "color-dodge" and the rest. Nil or
+// empty is `normal`, meaning ordinary source-over compositing.
+//
+// Core Animation does the whole feature in one property on macOS:
+// `CALayer.compositingFilter` takes a Core Image blend-mode filter and blends
+// the layer with what is already beneath it. The keyword maps onto one
+// `CI<Name>BlendMode` per CSS mode, including `plus-lighter`, which GSK has no
+// node for.
+- (void)setRnBlendModeName:(nullable NSString *)name;
+
+// The keyword that was set, or nil: what the app asked for.
+@property(nonatomic, readonly, nullable) NSString *rnBlendModeName;
+
+// The name of the Core Image filter that keyword resolved to, or nil. Public for
+// the tests, which assert the mapping and that Core Image has each filter: a
+// compositing filter cannot be seen in a snapshot, because `renderInContext:`
+// composites nothing.
+@property(nonatomic, readonly, nullable) NSString *rnBlendFilterName;
+
 // Set on the surface root. See RnAppKitInputHandler.
 @property(nonatomic, weak, nullable) id<RnAppKitInputHandler> rnInputHandler;
 
@@ -404,6 +874,28 @@ typedef NS_ENUM(NSInteger, RnAppKitControlKind) {
 // job is to have one covering it. That view is not an RnAppKitView, so it stays
 // out of the paint order, out of hit testing and out of `describeTree`'s
 // children -- the numbers are reported on the ScrollView's own line instead.
+// `indicatorStyle`, arriving as the colour `core/ScrollIndicator.h` resolved it
+// to rather than as the enum: the mapping is the same on all three desktops and
+// belongs in one place, and this layer knows nothing about React Native's
+// vocabulary.
+- (void)setRnScrollIndicatorColourRed:(CGFloat)red
+                                green:(CGFloat)green
+                                 blue:(CGFloat)blue
+                                alpha:(CGFloat)alpha;
+
+// The hairline around the thumb, which `indicatorStyle: 'default'` has and the
+// other two styles do not: iOS's default is black with a white border, and
+// that border is the whole difference between `default` and `black`. A
+// transparent colour means none. Resolved by `core/ScrollIndicator.h`, like
+// the fill, so the three hosts cannot drift.
+- (void)setRnScrollIndicatorBorderColourRed:(CGFloat)red
+                                      green:(CGFloat)green
+                                       blue:(CGFloat)blue
+                                      alpha:(CGFloat)alpha;
+// What that colour is now, for the test suite: the thumb is drawn into a layer
+// a test can rasterise, but reading the colour back is the cheaper assertion.
+- (NSColor *)rnScrollIndicatorColour;
+
 - (void)setRnScrollIndicatorVerticalOffset:(CGFloat)verticalOffset
                             verticalLength:(CGFloat)verticalLength
                           horizontalOffset:(CGFloat)horizontalOffset