react-x11 2.10.2 → 2.12.0

package/src/styles.js

@@ -6,6 +6,11 @@
 import { cssColorStraight } from 'ntk';
 
 import { parseBoxShadow, parseLinearGradient } from './decorations.js';
+import {
+  validateGridValue,
+  GRID_CONTAINER_PROPS,
+  GRID_ITEM_PROPS,
+} from './grid.js';
 import { Yoga } from './yoga.js';
 
 const FLEX_DIRECTION = {
@@ -47,8 +52,34 @@ const POSITION = {
   absolute: Yoga.POSITION_TYPE_ABSOLUTE,
 };
 
+/**
+ * Yoga's position type for a `position` value. `static`, `relative` and
+ * `absolute` are yoga's own. Everything else — `sticky`, and every position
+ * registered with `registerPosition` (src/layouts.js) — is laid out in flow
+ * exactly as `relative` is and moved afterwards: placing is not something
+ * layout does (nodes/position.js, `WindowNode._placeNodes`). What differs is the
+ * insets, which are the placement's to read — thresholds, for sticky — so
+ * yoga must never see them as offsets (`applyLayoutStyle`).
+ */
+const positionTypeOf = (v) =>
+  typeof v === 'string' && Object.hasOwn(POSITION, v)
+    ? POSITION[v]
+    : Yoga.POSITION_TYPE_RELATIVE;
+
+/** Whether a `position` is placed after layout rather than by it. */
+const isPlacedPosition = (v) =>
+  v != null && !(typeof v === 'string' && Object.hasOwn(POSITION, v));
+
+/** The properties that are an offset under `relative` and `absolute`, and the
+ *  placement's to read under any other — see `applyLayoutStyle`. */
+const INSETS = new Set(['top', 'right', 'bottom', 'left', 'start', 'end']);
+
+/** `'grid'` is a flex item to yoga: the box takes its place in its parent's
+ *  line like any other, and its own children are the grid's to arrange — a
+ *  layout host (src/grid.js, nodes/layouthost.js). */
 const DISPLAY = {
   flex: Yoga.DISPLAY_FLEX,
+  grid: Yoga.DISPLAY_FLEX,
   none: Yoga.DISPLAY_NONE,
 };
 
@@ -129,10 +160,7 @@ const LAYOUT_APPLIERS = {
   flexGrow: (n, v) => n.setFlexGrow(v ?? 0),
   flexShrink: (n, v) => n.setFlexShrink(v ?? 1),
   flexBasis: (n, v) => n.setFlexBasis(v),
-  position: (n, v) =>
-    n.setPositionType(
-      pick(POSITION, v, 'position') ?? Yoga.POSITION_TYPE_RELATIVE,
-    ),
+  position: (n, v) => n.setPositionType(positionTypeOf(v)),
   // Which way the boxes under this one run. Everything else in this file is
   // physical; this is the one property that decides what "start" means, and
   // yoga inherits it down its own tree — so a `<box>` that sets it mirrors
@@ -455,6 +483,18 @@ const STYLE_PROPS = new Set([
   // the ones that say it. Neither layout nor paint: it changes nothing about
   // this node, only what the blocks under it resolve against.
   'container',
+  // A registered layout algorithm that arranges this node's children — CSS's
+  // `display: layout(name)`, with the algorithm's options written beside the
+  // name — and what a child tells the one arranging it, CSS's child input
+  // properties (docs/styling.md, "Custom layouts"). Layout in every sense
+  // but yoga's: the node side reads them (nodes/layouthost.js).
+  'layout',
+  'layoutItem',
+  // CSS grid's own properties, on a `display: 'grid'` box and on each of its
+  // children (docs/styling.md, "Grid"). Layout in every sense but yoga's, like
+  // the two above: the grid reads them off the style (src/grid.js).
+  ...GRID_CONTAINER_PROPS,
+  ...GRID_ITEM_PROPS,
 ]);
 
 export const isStyleProp = (name) => STYLE_PROPS.has(name);
@@ -497,7 +537,7 @@ const SIZE_QUERY = /^@(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
  * *when* it is answered — a container's size is what a layout pass
  * produces, not what one starts from, so the blocks are resolved after the
  * pass and the tree laid out once more if an answer moved
- * (nodes.js, `_resolveContainerQueries`).
+ * (nodes/queries.js, `_resolveContainerQueries`).
  */
 const CONTAINER_QUERY =
   /^@container(?:\s+([A-Za-z_][\w-]*))?\s+(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/;
@@ -618,7 +658,7 @@ export function containerQueryNames(style) {
  * Which of a style's container blocks match, as one string with a character
  * per block in declaration order. What a node remembers between layout
  * passes so a re-resolution runs only when an answer actually moved, and
- * what the oscillation check compares (nodes.js `_resolveContainerQueries`).
+ * what the oscillation check compares (nodes/queries.js `_resolveContainerQueries`).
  */
 export function containerAnswers(style, containers) {
   let out = '';
@@ -690,21 +730,27 @@ function queryMatches(q, size, supports, containers) {
   }
 }
 
+const GRID_VALUES = new Set([...GRID_CONTAINER_PROPS, ...GRID_ITEM_PROPS]);
+
 /**
- * The two style values that are a small language rather than a number, and
- * therefore the two that can be *wrong* rather than merely absent. Parsed in
+ * The style values that are a small language rather than a number — a
+ * gradient, a shadow, and grid's track lists, areas and lines — and
+ * therefore the ones that can be *wrong* rather than merely absent. Parsed in
  * development wherever they are written — including inside a state block,
  * which is the half of the surface a `continue` used to skip — so the error
  * naming the property and the expected spelling arrives at the call site
- * instead of as a blank panel three commits later.
+ * instead of as a blank panel three commits later. A grid value goes through
+ * the parser the layout itself runs (src/grid.js), so the two agree.
  *
  * Tokens are still unresolved here (`$accent` is a colour as far as the
  * grammar is concerned), so this checks the shape and never the colours.
  */
 function validateValue(key, value, where) {
-  if (key !== 'backgroundImage' && key !== 'boxShadow') return;
+  const grid = GRID_VALUES.has(key);
+  if (!grid && key !== 'backgroundImage' && key !== 'boxShadow') return;
   try {
-    if (key === 'backgroundImage') parseLinearGradient(value);
+    if (grid) validateGridValue(key, value);
+    else if (key === 'backgroundImage') parseLinearGradient(value);
     else parseBoxShadow(value);
   } catch (err) {
     // the parser names the property and the grammar; only the call site is
@@ -714,6 +760,22 @@ function validateValue(key, value, where) {
   }
 }
 
+const ALGORITHM_NAME = /^[A-Za-z_][\w-]*$/;
+
+/** A plain object of options — what `layoutItem` is, and what a `layout` or
+ *  a registered `position` written with its options is. */
+const isOptionBag = (v) =>
+  v == null || (typeof v === 'object' && !Array.isArray(v));
+
+/** A `layout` / `position` value: a name, or one written with its options —
+ *  `'masonry'`, `{ name: 'masonry', columns: 3 }`. Whether the name is
+ *  registered is the node's to find out when it resolves the style: an
+ *  algorithm may be registered after the style that names it is written. */
+const isAlgorithm = (v) =>
+  v == null ||
+  (typeof v === 'string' && ALGORITHM_NAME.test(v)) ||
+  (isOptionBag(v) && typeof v.name === 'string' && ALGORITHM_NAME.test(v.name));
+
 function validateStyle(style, where) {
   for (const key of Object.keys(style)) {
     if (isQuery(key)) {
@@ -765,6 +827,28 @@ function validateStyle(style, where) {
           "digits, '_' and '-', not starting with a digit)",
       );
     }
+    if (key === 'layout' && !isAlgorithm(style[key])) {
+      throw new Error(
+        `react-x11: invalid layout ${JSON.stringify(style[key])} in ${where} ` +
+          "(expected a registered name like 'masonry', or { name: 'masonry' } " +
+          "with the layout's options beside it)",
+      );
+    }
+    if (key === 'position' && !isAlgorithm(style[key])) {
+      throw new Error(
+        `react-x11: invalid position ${JSON.stringify(style[key])} in ` +
+          `${where} (expected 'static', 'relative', 'absolute', 'sticky', or ` +
+          'a position registered with registerPosition — its name, or ' +
+          "{ name: '…' } with its options beside it)",
+      );
+    }
+    if (key === 'layoutItem' && !isOptionBag(style[key])) {
+      throw new Error(
+        `react-x11: invalid layoutItem ${JSON.stringify(style[key])} in ` +
+          `${where} (expected an object of the options the layout arranging ` +
+          'this node reads, like { span: 2 })',
+      );
+    }
     if (key === 'flex' && !isFlexShorthand(style[key])) {
       throw new Error(
         `react-x11: invalid flex ${JSON.stringify(style[key])} in ${where} ` +
@@ -882,6 +966,10 @@ const NOT_ANIMATABLE = new Set([
   // nothing is drawn from it, so there is no frame in which a halfway value
   // would be visible — and it may be an object, which does not lerp
   'hitSlop',
+  // a grid's tracks and a child's lines: a count of 3.5 columns, or line
+  // 2.5, is no grid at all, and a track list is a string
+  ...GRID_CONTAINER_PROPS,
+  ...GRID_ITEM_PROPS,
 ]);
 
 export const isAnimatableProp = (name) =>
@@ -1364,7 +1452,7 @@ export function stripTokens(style) {
  * anyone hears about it: mistakes are pushed onto `problems` and the caller
  * decides what one costs. Resolving itself never throws — it runs from a
  * commit and from an X event alike, and only the caller knows whether React
- * is on the stack to route a throw to a boundary (src/nodes.js).
+ * is on the stack to route a throw to a boundary (src/nodes/cascade.js).
  *
  * A cache hit replays the problems it recorded, so the second node to wear a
  * misspelled shared style is reported like the first.
@@ -1658,13 +1746,21 @@ export const createLayoutNode = () => Yoga.Node.create(layoutConfig());
 export function measuringExactly(measure) {
   const cfg = layoutConfig();
   cfg.setPointScaleFactor(0);
+  exactDepth++;
   try {
     return measure();
   } finally {
+    exactDepth--;
     cfg.setPointScaleFactor(1);
   }
 }
 
+let exactDepth = 0;
+
+/** Whether yoga is measuring off the pixel grid right now: a size taken in
+ *  here is not the size the same layout comes to on it. */
+export const isMeasuringExactly = () => exactDepth > 0;
+
 /**
  * The yoga defaults that are not CSS's, written once per node.
  *
@@ -1676,7 +1772,7 @@ export function measuringExactly(measure) {
  * The pair to it is the automatic minimum size — a flex item that may shrink
  * still cannot shrink below its content unless it says so. Yoga has no such
  * rule, so the renderer measures the floors itself; see `Node`'s content
- * floors in nodes.js.
+ * floors in nodes/window/floors.js.
  */
 export function applyLayoutDefaults(yogaNode) {
   yogaNode.setFlexShrink(1);
@@ -1688,15 +1784,41 @@ export function applyLayoutDefaults(yogaNode) {
  */
 export function applyLayoutStyle(yogaNode, props, oldProps = {}) {
   let changed = false;
+  // A placed node's insets — sticky's thresholds, or whatever a registered
+  // position reads them as — are the placement's, never offsets: yoga gets
+  // `undefined` for them, and a node that becomes placed (or stops) has all
+  // six re-sent whether or not they changed. The flip still counts as a
+  // change: the pass it asks for is what places the node.
+  const placed = isPlacedPosition(props.position);
+  const flipped = placed !== isPlacedPosition(oldProps.position);
   for (const key of Object.keys(LAYOUT_APPLIERS)) {
-    if (props[key] !== oldProps[key]) {
-      LAYOUT_APPLIERS[key](yogaNode, props[key]);
+    const moved =
+      key === 'position'
+        ? !samePosition(props.position, oldProps.position)
+        : props[key] !== oldProps[key];
+    if (moved || (flipped && INSETS.has(key))) {
+      LAYOUT_APPLIERS[key](
+        yogaNode,
+        placed && INSETS.has(key) ? undefined : props[key],
+      );
       changed = true;
     }
   }
   return changed;
 }
 
+/** Two `position` values asking for the same thing. A registered one written
+ *  with its options is an object, and an inline object is a new one every
+ *  render — which must not cost a layout pass per commit. */
+function samePosition(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  for (const key of keys) if (a[key] !== b[key]) return false;
+  return true;
+}
+
 /** @returns true if any paint-only prop changed */
 export function paintPropsChanged(props, oldProps = {}) {
   for (const key of PAINT_PROPS) {

package/src/svgnodes.js

@@ -12,7 +12,8 @@
 // grain for it.
 import { SvgView } from 'ntk';
 
-import { Node, intrinsicSize } from './nodes.js';
+import { Node } from './nodes/node.js';
+import { intrinsicSize } from './nodes/layout.js';
 import { isLayoutProp, isPaintProp } from './styles.js';
 
 // SVG attributes that are camelCase in SVG itself; every other camelCase

package/src/testing/harness.js

@@ -9,7 +9,7 @@
 
 import React from 'react';
 import { createRoot } from '../Reconciler.js';
-import { setAnimationClock } from '../nodes.js';
+import { setAnimationClock } from '../nodes/animation.js';
 import { setAppearanceForTests } from '../appearance.js';
 
 // A test process must not register with the desktop's live AT-SPI registry —
@@ -383,7 +383,7 @@ let clockInstalled = false;
 /**
  * Drive transitions from a number you control instead of from wall-clock
  * time. `setAnimationClock` exists for exactly this; it was reachable only
- * through a deep import into `src/nodes.js`.
+ * through a deep import into `src/nodes/animation.js`.
  *
  * ```js
  * const clock = withFrameClock();

package/src/textselection.js

@@ -9,7 +9,7 @@
 //
 // **A surface is a `selectable` element, and its participants are whatever
 // under it can answer for its own text.** An element joins by implementing
-// the four accessors in nodes.js (`textContent`, `textIndexAt`,
+// the four accessors in nodes/selectable.js (`textContent`, `textIndexAt`,
 // `textCaretRect`, `textRangeRects`) — `<text>` does, and so does a terminal
 // or a log view written outside this package. There is no registration call
 // and no list of blessed kinds: a document is a tree, and the tree is walked.
@@ -226,7 +226,7 @@ export class TextSelection {
    * pointer is: a press landed on the wrong character and a drag stopped
    * short at half its distance. The X event underneath already carries the
    * device numbers; an event synthesized without one is multiplied up, the
-   * way every other pointer consumer in nodes.js does it.
+   * way every other pointer consumer in src/nodes/ does it.
    */
   devicePoint(ev) {
     const scale = this.node.scale > 0 ? this.node.scale : 1;
@@ -407,7 +407,9 @@ export class TextSelection {
   }
 
   /** Take PRIMARY, which in X is what "there is a selection here" means to
-   * every other application on the display. */
+   * every other application on the display. macOS has no PRIMARY, and the
+   * cocoa backend's clipboard answers the write with nothing
+   * (src/cocoa/app.js) — there, a selection is never a copy. */
   own() {
     if (this.isCollapsed) return;
     takeVisibleSelection(this.node);

package/src/trace-registry.js

@@ -1,6 +1,6 @@
 // The seam between the renderer and the optional debug module.
 //
-// Reconciler.js and nodes.js import this file, so it has to stay safe to
+// Reconciler.js and nodes/window/flush.js import this file, so it has to stay safe to
 // bundle for the browser playground: no node builtins, no side effects,
 // nothing but a registry of live connections and a pair of hook slots. The
 // heavy half (protocol parsing, sinks, file writing) lives in debug.js and

package/src/types/components.d.ts

@@ -125,6 +125,20 @@ export interface Theme {
   direction: 'ltr' | 'rtl';
   paddingX: number;
   paddingY: number;
+  /**
+   * Not a colour: whether the widgets wear the **platform's own control
+   * bezels**. `'auto'` (the default) takes them wherever the backend has
+   * them — today the Cocoa backend, never X11 — `'native'` asks for them
+   * and says so in development where there are none, and `'drawn'` keeps
+   * this library's own rendering everywhere.
+   *
+   * It lives here rather than in `style` because whether an app looks
+   * native is an app-identity decision, not a per-node one;
+   * {@link NativeControlProp.native} is the per-control override, and
+   * `useSupports('nativeControls')` is how application code asks what this
+   * backend can do. See docs/components.md and docs/macos.md.
+   */
+  controls?: 'auto' | 'native' | 'drawn';
 }
 
 export interface ThemeProviderProps {
@@ -194,6 +208,20 @@ export function useDirection(): 'ltr' | 'rtl';
 /** Props a widget passes through to the `<box>` it renders. */
 type WidgetProps = Omit<BoxProps, 'children' | 'style' | 'ref'>;
 
+/**
+ * The per-instance escape hatch from the platform's own control bezel, for
+ * the one custom-branded control in an otherwise native app.
+ *
+ * The policy proper is {@link Theme.controls}; this overrides it for this
+ * control. `false` keeps the drawn rendering — which is what a control
+ * naming its own colours in `style` should say, because a bezel the system
+ * draws ignores them. `true` asks for the bezel regardless of the theme's
+ * policy, and is a development warning on a backend that has none.
+ */
+interface NativeControlProp {
+  native?: boolean;
+}
+
 /**
  * What a value widget's `onChange` receives — one signature across the
  * library, so `onChange={formik.handleChange}` wires to a `Checkbox` exactly
@@ -279,7 +307,7 @@ export const iconNames: readonly IconName[];
 /** The default icon box for a given `fontSize`. */
 export function iconSize(fontSize: number): number;
 
-export interface ButtonProps extends WidgetProps {
+export interface ButtonProps extends WidgetProps, NativeControlProp {
   children?: ReactNode;
   label?: string;
   onPress?: (ev: MouseEvent<DrawnNode>) => void;
@@ -328,7 +356,8 @@ export interface PasswordInputProps extends WidgetProps, NamedWidget {
 }
 export const PasswordInput: ComponentType<PasswordInputProps>;
 
-export interface CheckboxProps extends WidgetProps, NamedWidget {
+export interface CheckboxProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   children?: ReactNode;
   label?: string;
   checked?: boolean;
@@ -346,7 +375,7 @@ export interface RadioGroupProps<T = unknown> extends WidgetProps, NamedWidget {
 }
 export function RadioGroup<T = unknown>(props: RadioGroupProps<T>): ReactNode;
 
-export interface RadioProps<T = unknown> {
+export interface RadioProps<T = unknown> extends NativeControlProp {
   value: T;
   children?: ReactNode;
   label?: string;
@@ -354,7 +383,8 @@ export interface RadioProps<T = unknown> {
 }
 export function Radio<T = unknown>(props: RadioProps<T>): ReactNode;
 
-export interface SwitchProps extends WidgetProps, NamedWidget {
+export interface SwitchProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   checked?: boolean;
   onChange?: (ev: WidgetChangeEvent<boolean>) => void;
   disabled?: boolean;
@@ -378,7 +408,8 @@ export interface ProgressBarProps extends WidgetProps {
 }
 export const ProgressBar: ComponentType<ProgressBarProps>;
 
-export interface SliderProps extends WidgetProps, NamedWidget {
+export interface SliderProps
+  extends WidgetProps, NamedWidget, NativeControlProp {
   value?: number;
   min?: number;
   max?: number;
@@ -462,7 +493,8 @@ export const Dialog: ComponentType<DialogProps>;
 /** An option, or a plain value used as both value and label. */
 export type SelectOption<T = unknown> = { value: T; label: string } | T;
 
-export interface SelectProps<T = unknown> extends WidgetProps, NamedWidget {
+export interface SelectProps<T = unknown>
+  extends WidgetProps, NamedWidget, NativeControlProp {
   value?: T;
   options?: readonly SelectOption<T>[];
   onChange?: (ev: WidgetChangeEvent<T>) => void;

package/src/types/elements.d.ts

@@ -222,7 +222,8 @@ export interface SelectionProps<T = DrawnNode> {
   /**
    * `true` makes this element a selection surface: a drag across the text
    * inside it selects, double and triple clicks take a word and a block,
-   * Ctrl+A and Ctrl+C work, and a release takes PRIMARY. It also makes the
+   * Ctrl+A and Ctrl+C work, and on X11 a release takes PRIMARY (macOS has
+   * none: there, only a copy reaches the pasteboard). It also makes the
    * element a focus target, so the keys have somewhere to arrive —
    * `tabIndex={-1}` keeps it out of the Tab cycle.
    *
@@ -649,6 +650,15 @@ export interface BoxProps
 
 /** What `overflow: 'scroll'` adds, on a `<box>` or a `<window>`. */
 export interface ScrollProps {
+  /**
+   * The offsets moved, by any route. The wheel, the keys, a bar and
+   * `scrollTo`/`scrollBy` report inside the call. Layout reports once its
+   * pass is over, after the frame that shows the move: a held `scrollTo`
+   * landing (one made before the pane's first layout, or past the extent
+   * the last pass measured), a `scrollIntoView` resolving, or the offset
+   * pulled back when the content shrinks or the viewport grows under it.
+   * Each report carries the offsets in force when it is delivered.
+   */
   onScroll?: (ev: ScrollEvent) => void;
   /** Fired from layout, so it arrives for a list nobody has scrolled yet. */
   onViewport?: (ev: ViewportEvent) => void;

package/src/types/nodes.d.ts

@@ -18,8 +18,17 @@ export interface DrawnNode {
    * was registered under. What queries and paint order match on:
    * `screen.all((n) => n.kind === 'gauge')`. */
   readonly kind: string;
-  /** Position and size within the owning window, valid after layout. */
+  /** Position and size within the owning window, valid after layout. In
+   * **device pixels**, like everything painted — a mouse event's `x`/`y`
+   * are logical, `scale` apart (docs/scale.md). `ev.nativeEvent.x`/`y` are
+   * the same point as `ev.x`/`y` already in this unit, which is what a
+   * pointer measured against a laid-out box wants. */
   readonly abs: Rect;
+  /** Device pixels per logical pixel for this node: the display's scale
+   * times any `scale` prop above it, resolved once and constant for the
+   * node's life. The number that converts between `abs` and the logical
+   * unit an app writes styles and reads events in. */
+  readonly scale: number;
   readonly parent: DrawnNode | null;
   readonly children: readonly DrawnNode[];
   /** Take the keyboard focus, if this node is focusable. Returns the node,
@@ -42,14 +51,18 @@ export interface DrawnNode {
   readonly direction: 'ltr' | 'rtl';
   /** Whether `node` is this node or a descendant of it (DOM `contains`). */
   contains(node: DrawnNode | null): boolean;
+  /** The boxes this node occupies, in **logical** pixels — already divided
+   * by `scale`, so they compare directly with an event's `x`/`y`. One rect
+   * for a box; one per line for wrapped text. */
   getClientRects(): Rect[];
 
   // --- text geometry (docs/elements.md, "Selection") ------------------------
   //
   // Every drawn node answers these; an element with no text answers `null`,
   // `0` and `[]`. Indices are **code points** and rectangles are in the
-  // owning window's coordinates — the same space as `abs` and a mouse
-  // event's `x`/`y`.
+  // owning window's coordinates — the same space as `abs`, which is device
+  // pixels: this seam speaks that unit deliberately, so a point taken from
+  // an event arrives through `ev.nativeEvent` or multiplied by `scale`.
 
   /** This element's text, or null when it has none. */
   textContent(): string | null;
@@ -110,8 +123,22 @@ export interface ScrollableNode extends DrawnNode {
   readonly scrollY: number;
   readonly contentWidth: number;
   readonly contentHeight: number;
-  /** A number scrolls the vertical axis; an object moves either or both. */
+  /**
+   * A number scrolls the vertical axis; an object moves either or both,
+   * clamped to the content. It answers at once from the extent the last
+   * layout pass measured. While a pass is owed — before the pane's first
+   * layout, or in the commit that added its new rows — whatever it asks past
+   * that extent is held too, and the pass answers it again against the
+   * content it measures, before the frame paints: `scrollTo(Infinity)` from
+   * a layout effect follows new rows to the end in the frame that shows
+   * them. `onScroll` reports the call's answer at once, and the pass's once
+   * that pass is over.
+   */
   scrollTo(to: number | ScrollTarget): void;
+  /**
+   * The same, by a delta. Made while a `scrollTo` is held for the pass, it
+   * moves on from where the pass puts the pane.
+   */
   scrollBy(by: number | ScrollTarget): void;
   /**
    * Is there room to move on the axis a delta names? What the wheel's
@@ -122,7 +149,8 @@ export interface ScrollableNode extends DrawnNode {
   /**
    * Scroll the minimum amount on both axes that makes a descendant fully
    * visible. Safe to call right after that node mounts — the request is
-   * resolved on the next layout pass, when it has geometry.
+   * resolved on the next layout pass, when it has geometry, and `onScroll`
+   * reports the move once that pass is over.
    */
   scrollIntoView(node: DrawnNode): void;
 }

package/src/types/screencolor.d.ts

@@ -6,22 +6,26 @@ import type { AbortSignalLike, WindowTarget } from './filedialog.js';
 import type { NtkApp } from './nodes.js';
 
 /** Which rung of the ladder answered — or would. */
-export type ScreenColorBackend = 'portal' | 'x11';
+export type ScreenColorBackend = 'cocoa' | 'portal' | 'x11';
 
 export interface PickScreenColorOptions {
   /**
    * The window the picker belongs to — `parent_window` for the portal, and
-   * (when it points at a mounted node) the connection the X11 rung grabs on.
-   * `useEyedropper()` infers it from the tree.
+   * (when it points at a mounted node) the app the cocoa rung samples
+   * through or the connection the X11 rung grabs on. `useEyedropper()`
+   * infers it from the tree.
    */
   parentWindow?: WindowTarget;
   /** Abort the pick. Closes the portal request, or releases the X11 grab —
-   * the grab is released **before** the rejection is reported. */
+   * the grab is released **before** the rejection is reported. On the cocoa
+   * rung it ends the wait only: `NSColorSampler` cannot be dismissed from
+   * code, so the loupe stays up until the user answers it. */
   signal?: AbortSignalLike;
   /** Force a rung, for kiosks and for tests. */
   backend?: ScreenColorBackend;
   /**
-   * The connection the X11 rung grabs and reads on. Required for that rung
+   * The app a pick runs through: the cocoa rung's `colorSampler`, or the
+   * connection the X11 rung grabs and reads on. Required for either rung
    * when `parentWindow` does not resolve to a mounted node — the hook passes
    * the tree's own.
    */
@@ -40,23 +44,25 @@ export declare class NoScreenColorError extends Error {
 }
 
 /**
- * Sample one pixel from the screen: the desktop's own picker
- * (`org.freedesktop.portal.Screenshot.PickColor`, Screenshot interface
- * version 2) where there is one, a crosshair pointer grab on plain X11
- * everywhere else.
+ * Sample one pixel from the screen: the system's own picker where there is
+ * one — `NSColorSampler` on the cocoa backend (`@windowkit/appkit` >= 0.9),
+ * `org.freedesktop.portal.Screenshot.PickColor` (Screenshot interface
+ * version 2) on a desktop that has it — and a crosshair pointer grab on
+ * plain X11 everywhere else.
  *
  * Resolves to `'#rrggbb'`, or `null` when the user cancelled — Escape on the
- * X11 rung, the dialog's own cancel on the portal. Rejects with
- * {@link NoScreenColorError} when neither rung is reachable.
+ * X11 rung, the dialog's own cancel on the portal, a dismissed sampler on
+ * cocoa. Rejects with {@link NoScreenColorError} when no rung is reachable.
  */
 export declare function pickScreenColor(
   options?: PickScreenColorOptions,
 ): Promise<string | null>;
 
 /**
- * Which rung this machine lands on, without grabbing anything. `'x11'` needs
- * a connection to answer with — pass `app`, or a `parentWindow` pointing at
- * a mounted node — and `null` means {@link pickScreenColor} would reject.
+ * Which rung this machine lands on, without showing or grabbing anything.
+ * `'cocoa'` and `'x11'` both need an app to answer through — pass `app`, or
+ * a `parentWindow` pointing at a mounted node — and `null` means
+ * {@link pickScreenColor} would reject.
  */
 export declare function screenColorBackend(
   options?: Pick<PickScreenColorOptions, 'app' | 'backend' | 'parentWindow'>,