@astryxdesign/core 0.7.8 → 0.7.9-canary.048476f

package/src/privateAttributes/menuPressLit.stylex.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @file privateAttributes/menuPressLit.stylex.ts
+ * @input The row that a held finger or pen lights in a menu
+ * @output Exports markMenuPressLit and clearMenuPressLit, which mark that row,
+ *   and isMenuPressLit, which reads the mark. It also exports
+ *   menuPressLitRowStyle, which paints the marked row. The hold pair,
+ *   holdMenuPressPaint and releaseMenuPressPaint, keeps the other rows off
+ *   their pressed paint, and isMenuPressPaintHeld reads that hold.
+ * @position Owner module of the private menu-press-lit attribute: the only
+ *   file that writes its name. The menu press model (hooks/useMenuPress.ts)
+ *   marks the row; DropdownMenu's rows compose the styles. No package entry
+ *   exports it.
+ *
+ * SYNC: Each row that composes menuPressLitRowStyle reads
+ *   `--_menu-row-focus-paint` in its `:focus` background, and a row with an
+ *   `:active` background reads `--_menu-row-active-paint` there:
+ * - /packages/core/src/DropdownMenu/DropdownMenuItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+const MENU_PRESS_LIT = 'data-astryx-menu-press-lit';
+const ACTIVE_PAINT = '--_menu-row-active-paint';
+
+/** Marks `row` as the row that a held finger or pen lights. */
+export function markMenuPressLit(row: Element): void {
+  row.setAttribute(MENU_PRESS_LIT, '');
+}
+
+/** Removes the mark from `row`. */
+export function clearMenuPressLit(row: Element): void {
+  row.removeAttribute(MENU_PRESS_LIT);
+}
+
+/** Whether a held finger or pen lights `row`. */
+export function isMenuPressLit(row: Element): boolean {
+  return row.hasAttribute(MENU_PRESS_LIT);
+}
+
+/**
+ * Keeps `menu`'s rows off their `:active` paint while a held finger or pen
+ * presses in it. The row the press began on stays `:active` as the press
+ * moves on. The lit row keeps the pressed overlay through its own mark.
+ */
+export function holdMenuPressPaint(menu: HTMLElement): void {
+  menu.style.setProperty(ACTIVE_PAINT, 'transparent');
+}
+
+/** Gives `menu`'s rows their `:active` paint back. */
+export function releaseMenuPressPaint(menu: HTMLElement): void {
+  menu.style.removeProperty(ACTIVE_PAINT);
+}
+
+/** Whether a held finger or pen keeps `menu`'s rows off their `:active` paint. */
+export function isMenuPressPaintHeld(menu: HTMLElement): boolean {
+  return menu.style.getPropertyValue(ACTIVE_PAINT) !== '';
+}
+
+/**
+ * A value for each attribute state. The index signature gives StyleX the value
+ * type, which it cannot read from a literal attribute key.
+ */
+type ByAttribute<Value> = Readonly<{
+  default: null;
+  [attribute: string]: Value | null;
+}>;
+
+const litRowPaint: Readonly<{
+  '--_menu-row-focus-paint': ByAttribute<string>;
+  '--_menu-row-active-paint': ByAttribute<string>;
+}> = {
+  '--_menu-row-focus-paint': {
+    default: null,
+    '[data-astryx-menu-press-lit]': colorVars['--color-overlay-pressed'],
+  },
+  '--_menu-row-active-paint': {
+    default: null,
+    '[data-astryx-menu-press-lit]': colorVars['--color-overlay-pressed'],
+  },
+};
+
+const styles = stylex.create({
+  row: {...litRowPaint},
+});
+
+/**
+ * Compose on a menu row whose `:focus` background is
+ * `var(--_menu-row-focus-paint, <hover overlay>)`, and whose `:active`
+ * background, if any, is `var(--_menu-row-active-paint, <pressed overlay>)`.
+ * The row paints the hover overlay on focus, and the pressed overlay while a
+ * held finger or pen lights it.
+ * Under a finger, the hover overlay is too faint to follow. The variable has
+ * no default: a layered stylesheet emits a default unlayered, and it would
+ * beat the attribute arm. The value resolves on the row, so a theme set on any
+ * ancestor applies. The style sets only a custom property, which shares no
+ * key with StyleX's CSS property type, so TypeScript needs the wider type.
+ */
+export const menuPressLitRowStyle = styles.row as StyleXStyles;

package/src/privateAttributes/press.stylex.ts

@@ -0,0 +1,244 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @astryx/no-hover-on-disabled -- Every hover branch is
+ * nested beneath ENABLED below, as in interactionOverlay.stylex.ts. */
+
+/**
+ * @file privateAttributes/press.stylex.ts
+ * @input StyleX, the semantic overlay color tokens, the touch press strength
+ *   (`pressVars`, utils/interactionOverlay.stylex.ts) and the row layer's
+ *   clocks (utils/rowPressLayer.stylex.ts)
+ * @output `rowPressLayerStyles`: the compositor press layer for list rows
+ *   (`cell`) and its own-image arms for a row on the `backgroundImage`
+ *   variant (`cellOnImage`)
+ * @position Owner module of the private press attribute for the row layer:
+ *   the press controller (utils/pressFeedback.ts) writes the attribute, and
+ *   this file reads it. No package entry exports it. Item and TreeList
+ *   compose these styles after their overlay variant;
+ *   utils/interactionOverlay.cell.test.ts tests them.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {pressVars} from '../utils/interactionOverlay.stylex';
+import {cellPressConsts} from '../utils/rowPressLayer.stylex';
+
+// The overlay's arm selectors (interactionOverlay.stylex.ts), restated here:
+// StyleX resolves a style's keys within its own file.
+const ENABLED = ':where(:not(:disabled,[aria-disabled="true"]))';
+const HOVER_HOVER = '@media (hover: hover)';
+const COARSE = '@media (pointer: coarse)';
+const PRESSED_ON = '[data-astryx-press="on"]';
+const PRESSED_FADING = '[data-astryx-press="fading"]';
+/**
+ * A press in any of its states: the row layer exists only then, so at rest a
+ * row's own `::before` and its stacking are untouched.
+ */
+const PRESSED_ANY =
+  ':is([data-astryx-press="on"],[data-astryx-press="fading"])';
+
+const PRESS_ALPHA = pressVars['--astryx-press-alpha'];
+
+const hoverImage = `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`;
+const pressedImage = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
+/** The overlay's paint, read back off the element (its gradient layer). */
+const pressedOverlayImage = 'var(--_press-paint-image)';
+
+/**
+ * The overlay's strength release (interactionOverlay.stylex.ts), restated so
+ * a fine pointer keeps it: the same keyframes, so the same animation.
+ */
+const pressRelease = stylex.keyframes({
+  from: {[PRESS_ALPHA]: 1},
+  to: {[PRESS_ALPHA]: 0},
+});
+
+/**
+ * The row layer's clock as CSS. It is the strength release's clock, scaled
+ * by the theme's `--_astryx-motion-tempo` up to 1.5, so the layer and the
+ * strength land together.
+ */
+const CELL_RELEASE = `calc(${cellPressConsts.cellReleaseMs}ms * min(var(--_astryx-motion-tempo, 1), 1.5))`;
+/** The same clock under Reduce Motion: a tempo may shorten it, never lengthen it. */
+const CELL_RELEASE_REDUCED = `min(${cellPressConsts.cellReleaseMs}ms, calc(${cellPressConsts.cellReleaseMs}ms * var(--_astryx-motion-tempo, 1)))`;
+const REDUCED_MOTION = '@media (prefers-reduced-motion: reduce)';
+
+/** Opacity 1 → 0: the row layer leaves; its fading arm runs it. */
+const cellRelease = stylex.keyframes({
+  from: {opacity: 1},
+  to: {opacity: 0},
+});
+
+/** The release's curve: the table's gentle ease-out. */
+const RELEASE_EASE = cellPressConsts.cellReleaseEase;
+
+export const rowPressLayerStyles = stylex.create({
+  /**
+   * A list row's touch press on a compositor layer (Item, and TreeList's row
+   * box), composed AFTER the row's overlay variant (StyleX is last-wins per
+   * property). The variant's own touch paint, a gradient whose strength is a
+   * registered custom property, animates on the main thread: while script
+   * runs, a pressed row would stay at full strength and every frame of the
+   * fade would paint. Here the press is an element-sized `::before` under the
+   * row's content whose OPACITY is the strength: `on` shows it at once and
+   * `fading` runs a keyframe animation of its opacity, 1 → 0, on the cell's
+   * release clock (`timing.press`), which engines run on the compositor:
+   * it keeps advancing while the main thread is blocked and lays out and
+   * paints nothing. Same pixels as the variant's paint at that strength. The
+   * variant keeps the hover and a mouse's `:active`. The row must be
+   * positioned (the layer is placed absolutely); `isolation: isolate` keeps
+   * the layer above the row's background (a selected fill) and below its
+   * content. The layer exists only while a press is on or releasing: at rest
+   * a row's own `::before` and its stacking are as they were; during a press
+   * the layer is the row's `::before`, so a caller's decoration there merges
+   * into the layer for that time (decorate with `::after` or a child).
+   *
+   * Under a finger only (a coarse primary pointer): a fine pointer keeps the
+   * variant exactly, with no layer, no stacking context and its own touch
+   * paint, so a desktop row is as it was.
+   */
+  cell: {
+    // The `backgroundColor` variant's own image arms (Item's), its touch
+    // paint yielding to the layer under a finger. Only the row's own image
+    // turns off: the press paint (`--_press-paint`) stays the variant's, so
+    // what a row's descendants paint from it still paints. A fine pointer
+    // keeps the arms exactly. `cellOnImage` is the same for the
+    // `backgroundImage` variant (TreeList's row box).
+    backgroundImage: {
+      default: null,
+      [ENABLED]: {
+        default: null,
+        [PRESSED_ON]: {default: pressedOverlayImage, [COARSE]: 'none'},
+        [PRESSED_FADING]: {default: pressedOverlayImage, [COARSE]: 'none'},
+      },
+    },
+    // Under a finger the strength's own release (a main-thread animation)
+    // is dropped: the layer fades instead, on the compositor. A row whose
+    // descendant fades at the row's strength (a radio row's circle) brings
+    // it back with `pressedAlpha`. A fine pointer keeps it as the variant
+    // declares it (its clock and curve are untouched).
+    animationName: {
+      default: null,
+      [PRESSED_FADING]: {default: pressRelease, [COARSE]: 'none'},
+    },
+    // The stacking context the layer needs, for a press only.
+    isolation: {
+      default: null,
+      [COARSE]: {default: null, [PRESSED_ANY]: 'isolate'},
+    },
+    // The whole layer is under a finger only, and only while a press is on
+    // or releasing: with a fine pointer none of it applies, and at rest a
+    // row's own `::before` is exactly as it was.
+    '::before': {
+      content: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [ENABLED]: {default: null, [PRESSED_ANY]: '""'},
+        },
+      },
+      position: {
+        default: null,
+        [COARSE]: {default: null, [PRESSED_ANY]: 'absolute'},
+      },
+      inset: {default: null, [COARSE]: {default: null, [PRESSED_ANY]: 0}},
+      zIndex: {default: null, [COARSE]: {default: null, [PRESSED_ANY]: -1}},
+      borderRadius: {
+        default: null,
+        [COARSE]: {default: null, [PRESSED_ANY]: 'inherit'},
+      },
+      pointerEvents: {
+        default: null,
+        [COARSE]: {default: null, [PRESSED_ANY]: 'none'},
+      },
+      backgroundColor: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [PRESSED_ANY]: colorVars['--color-overlay-pressed'],
+        },
+      },
+      // On at once while the press is believed; nothing transitions it.
+      opacity: {
+        default: null,
+        [COARSE]: {default: null, [PRESSED_ON]: 1, [PRESSED_FADING]: 0},
+      },
+      animationName: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [ENABLED]: {default: null, [PRESSED_FADING]: cellRelease},
+        },
+      },
+      animationDuration: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [PRESSED_FADING]: {
+            default: CELL_RELEASE,
+            [REDUCED_MOTION]: CELL_RELEASE_REDUCED,
+          },
+        },
+      },
+      animationTimingFunction: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [PRESSED_FADING]: RELEASE_EASE,
+        },
+      },
+      animationFillMode: {
+        default: null,
+        [COARSE]: {default: null, [PRESSED_FADING]: 'both'},
+      },
+    },
+  },
+  /**
+   * A row that keeps no press paint of its own, composed after `cell`: a
+   * radio row, whose circle paints the press. The row paints no overlay
+   * image, keeps the strength's own release (the circle's layer reads the
+   * strength), and under a finger has no `::before` box and is no stacking
+   * context during a press.
+   */
+  cellWithoutLayer: {
+    backgroundImage: 'none',
+    animationName: {default: null, [PRESSED_FADING]: pressRelease},
+    isolation: {
+      default: null,
+      [COARSE]: {default: null, [PRESSED_ANY]: 'auto'},
+    },
+    '::before': {
+      content: {
+        default: null,
+        [COARSE]: {
+          default: null,
+          [ENABLED]: {default: null, [PRESSED_ANY]: 'none'},
+        },
+      },
+    },
+  },
+  /**
+   * `cell`'s own-image arms for a row on the `backgroundImage` variant
+   * (TreeList's row box), composed after `cell`: the variant's arms, its
+   * touch press paint yielding to the layer under a coarse primary pointer.
+   */
+  cellOnImage: {
+    backgroundImage: {
+      default: null,
+      [ENABLED]: {
+        default: null,
+        ':active': {
+          default: pressedImage,
+          [COARSE]: 'none',
+        },
+        [HOVER_HOVER]: {
+          default: null,
+          ':hover': hoverImage,
+          ':active': pressedImage,
+        },
+        [PRESSED_ON]: {default: pressedOverlayImage, [COARSE]: 'none'},
+        [PRESSED_FADING]: {default: pressedOverlayImage, [COARSE]: 'none'},
+      },
+    },
+  },
+});

package/src/theme/tokens.stylex.ts

@@ -24,7 +24,7 @@ import * as stylex from '@stylexjs/stylex';
 
 export const colorDefaults = {
   // Core semantic
-  '--color-accent': 'light-dark(#0064E0, #2694FE)',
+  '--color-accent': 'light-dark(#0064E0, #0171E3)',
   '--color-accent-muted': 'light-dark(#0082FB33, #0082FB3F)',
   '--color-on-accent': 'light-dark(#FFFFFF, #FFFFFF)',
   '--color-neutral':

package/src/utils/flatTree.ts

@@ -3,11 +3,12 @@
 /**
  * @file flatTree.ts
  * @input A DOM node
- * @output Exports parentAcrossShadow, and containsAlongFlatTree, which walks it
+ * @output Exports parentAcrossShadow, containsAlongFlatTree, which walks it,
+ *   and deepActiveElement
  * @position The flat-tree parent the browser scrolls and dispatches
- *   through, shared by the gesture host's native-scroll probe and the
+ *   through, shared by the gesture host's native-scroll probe, the
  *   selection lock (which the press feedback controller uses without the
- *   gesture system)
+ *   gesture system) and the Layer module's input hold
  */
 
 /** The node's parent, crossing out of shadow roots. */
@@ -38,3 +39,14 @@ export function containsAlongFlatTree(ancestor: Node, node: Node): boolean {
   }
   return false;
 }
+
+/** The focused element of `doc`, inside open shadow roots too. */
+export function deepActiveElement(
+  doc: Document | null | undefined,
+): Element | null {
+  let active = doc?.activeElement ?? null;
+  while (active?.shadowRoot?.activeElement != null) {
+    active = active.shadowRoot.activeElement;
+  }
+  return active;
+}

package/src/utils/hitArea.ts

@@ -24,6 +24,9 @@
 // live control measures: only under a coarse primary pointer (AST-094), only on
 // screen, and in one read pass per frame within a 4 ms budget. Until the first
 // pass the insets are 0, so first paint never overlaps anything.
+// The insets are lengths in the control's own box, so a pass measures in its
+// layout px. A layer that opens from a smaller scale then keeps the insets of
+// the size it settles at.
 
 import {observeContent} from './sharedMutationObserver';
 
@@ -330,6 +333,95 @@ function plainRect(element: Element): HitRect {
   return {left, top, right, bottom};
 }
 
+/** A box that the transforms around it leave at its layout size. */
+const UNSCALED = {x: 1, y: 1} as const;
+
+/** One axis of a box's scale on screen: its client size over its layout size. */
+function axisScale(onScreen: number, layout: number): number {
+  if (!(layout > 0) || !(onScreen > 0)) {
+    return 1;
+  }
+  const scale = onScreen / layout;
+  // Within rounding of 1 the box is at its layout size: no change to the rects.
+  return Math.abs(scale - 1) < 1e-3 ? 1 : scale;
+}
+
+/**
+ * How far the transforms around `element` scale its box on screen, per axis.
+ * A layer that opens from a smaller scale scales every rect inside it, while
+ * the layout box keeps the size the layer settles at. Only a scale is
+ * expected: a rotated or skewed box would read as a larger scale.
+ */
+function screenScale(
+  element: Element,
+  onScreen: HitRect,
+): {x: number; y: number} {
+  // The offset size is the layout size in whole pixels, unaffected by
+  // transforms, and costs no style resolution. A box with none, such as an SVG
+  // element or a jsdom box, reads as unscaled.
+  const box = element as Partial<HTMLElement>;
+  const offsetWidth = box.offsetWidth ?? 0;
+  const offsetHeight = box.offsetHeight ?? 0;
+  if (offsetWidth === 0 || offsetHeight === 0) {
+    return UNSCALED;
+  }
+  // Within a pixel of its layout size the box reads as unscaled, which bounds
+  // the inset error at about a pixel. Only a box that a transform shrinks or
+  // grows reads its exact size from the computed style.
+  if (
+    Math.abs(onScreen.right - onScreen.left - offsetWidth) <= 1 &&
+    Math.abs(onScreen.bottom - onScreen.top - offsetHeight) <= 1
+  ) {
+    return UNSCALED;
+  }
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  if (style == null || !style.width.endsWith('px')) {
+    return UNSCALED;
+  }
+  const px = (value: string) => Number.parseFloat(value) || 0;
+  const isContentBox = style.boxSizing !== 'border-box';
+  const width =
+    px(style.width) +
+    (isContentBox
+      ? px(style.paddingLeft) +
+        px(style.paddingRight) +
+        px(style.borderLeftWidth) +
+        px(style.borderRightWidth)
+      : 0);
+  const height =
+    px(style.height) +
+    (isContentBox
+      ? px(style.paddingTop) +
+        px(style.paddingBottom) +
+        px(style.borderTopWidth) +
+        px(style.borderBottomWidth)
+      : 0);
+  return {
+    x: axisScale(onScreen.right - onScreen.left, width),
+    y: axisScale(onScreen.bottom - onScreen.top, height),
+  };
+}
+
+/**
+ * `rect` in the layout px of the box at `origin`: its offset from `origin`,
+ * divided by that box's scale on screen.
+ */
+function inLayout(
+  rect: HitRect,
+  origin: HitRect,
+  scale: {x: number; y: number},
+): HitRect {
+  if (scale.x === 1 && scale.y === 1) {
+    return rect;
+  }
+  return {
+    left: origin.left + (rect.left - origin.left) / scale.x,
+    top: origin.top + (rect.top - origin.top) / scale.y,
+    right: origin.left + (rect.right - origin.left) / scale.x,
+    bottom: origin.top + (rect.bottom - origin.top) / scale.y,
+  };
+}
+
 interface Candidate {
   readonly element: Element;
   readonly rect: HitRect;
@@ -373,14 +465,15 @@ function measureOne(
   candidates: ReadonlyArray<Candidate>,
 ): {target: HitRect; insets: HitInsets; neighbours: HitRect[]} {
   const target = plainRect(watch.element);
+  const scale = screenScale(watch.element, target);
   // Two targets each growing up to half the minimum reach each other from a
   // minimum apart.
   const reach = Math.max(0, watch.minSize);
   const band = grown(target, {
-    top: reach,
-    right: reach,
-    bottom: reach,
-    left: reach,
+    top: reach * scale.y,
+    right: reach * scale.x,
+    bottom: reach * scale.y,
+    left: reach * scale.x,
   });
   const neighbours = candidates
     .filter(
@@ -393,7 +486,16 @@ function measureOne(
     .map(({rect}) => rect);
   return {
     target,
-    insets: clampedHitInsets(target, neighbours, watch.minSize),
+    // The insets are in the control's layout px. The returned rects stay in
+    // screen px for a touch's distance checks. A neighbour maps by the
+    // control's scale, as if it is in the same layer. A neighbour outside that
+    // layer then reads farther away. A touch compares screen distances, so it
+    // still counts that neighbour.
+    insets: clampedHitInsets(
+      inLayout(target, target, scale),
+      neighbours.map(rect => inLayout(rect, target, scale)),
+      watch.minSize,
+    ),
     neighbours,
   };
 }

package/src/utils/inputStream.ts

@@ -4,7 +4,8 @@
  * @file inputStream.ts
  * @input A window, and subscribers to its input events (the press feedback
  *   controller, the gesture host)
- * @output subscribeInput
+ * @output subscribeInput, and getLastPointerType: the type of the latest
+ *   pointer event the stream delivered
  * @position The one entry for document-wide input listeners in core: one
  *   native listener per event type on the window's capture phase, shared by
  *   every subscriber
@@ -22,18 +23,21 @@
 // `blur` or `focus`. A subscriber for the window's own event checks
 // `event.target`.
 //
-// Subscribers run in subscription order. One that throws is reported, and
-// the rest still run.
+// Subscribers run in subscription order, after the ones subscribed `first`.
+// A first subscriber that returns `true` ends the dispatch: no later
+// subscriber hears the event. One that throws is reported, and the rest still
+// run.
 //
 // A type's native listener is passive, so it blocks no scroll. It is
 // non-passive only while a subscriber that cancels the event
 // (`{cancels: true}`) is subscribed. With no subscriber left, it is removed.
 
-type InputListener = (event: Event) => void;
+type InputListener = (event: Event) => unknown;
 
 interface Subscriber {
   readonly listener: InputListener;
   readonly cancels: boolean;
+  readonly isFirst: boolean;
 }
 
 interface Channel {
@@ -50,12 +54,30 @@ export interface InputSubscriptionOptions {
    * @default false
    */
   readonly cancels?: boolean;
+  /**
+   * The subscriber runs before every subscriber that is not first. When it
+   * returns `true`, no later subscriber hears the event.
+   * @default false
+   */
+  readonly first?: boolean;
 }
 
 /** The events a window's capture phase sees: its own, and the document's. */
 export type InputEventMap = WindowEventMap & DocumentEventMap;
 
 const streams = new WeakMap<Window, Map<string, Channel>>();
+/** The type of the latest pointer event each window's stream delivered. */
+const lastPointerTypes = new WeakMap<Window, string>();
+
+/**
+ * The type of the latest pointer event `view`'s stream delivered: `mouse`,
+ * `pen` or `touch`, or `null` before any. The stream hears a pointer event
+ * type only while a subscriber listens to it, as press feedback does on any
+ * page with a pressable. Reading it adds no listener.
+ */
+export function getLastPointerType(view: Window): string | null {
+  return lastPointerTypes.get(view) ?? null;
+}
 
 /**
  * Listen to `type` on `view`'s capture phase through its shared native
@@ -64,8 +86,8 @@ const streams = new WeakMap<Window, Map<string, Channel>>();
 export function subscribeInput<K extends keyof InputEventMap>(
   view: Window,
   type: K,
-  listener: (event: InputEventMap[K]) => void,
-  {cancels = false}: InputSubscriptionOptions = {},
+  listener: (event: InputEventMap[K]) => unknown,
+  {cancels = false, first = false}: InputSubscriptionOptions = {},
 ): () => void {
   let channels = streams.get(view);
   if (channels == null) {
@@ -80,8 +102,16 @@ export function subscribeInput<K extends keyof InputEventMap>(
   const subscriber: Subscriber = {
     listener: listener as InputListener,
     cancels,
+    isFirst: first,
   };
-  channel.subscribers.push(subscriber);
+  const firstLater = first
+    ? channel.subscribers.findIndex(other => !other.isFirst)
+    : -1;
+  if (firstLater === -1) {
+    channel.subscribers.push(subscriber);
+  } else {
+    channel.subscribers.splice(firstLater, 0, subscriber);
+  }
   register(view, type, channel);
   let isSubscribed = true;
   return () => {
@@ -124,12 +154,17 @@ function register(view: Window, type: string, channel: Channel): void {
   if (wanted == null) {
     return;
   }
-  const listener: InputListener = event => dispatch(channel, event);
+  const listener: InputListener = event => dispatch(view, channel, event);
   view.addEventListener(type, listener, {capture: true, passive: !wanted});
   channel.native = {listener, cancels: wanted};
 }
 
-function dispatch(channel: Channel, event: Event): void {
+function dispatch(view: Window, channel: Channel, event: Event): void {
+  // Recorded before any subscriber runs, so each reads the pointer at hand.
+  const {pointerType} = event as Partial<PointerEvent>;
+  if (typeof pointerType === 'string' && pointerType !== '') {
+    lastPointerTypes.set(view, pointerType);
+  }
   // A subscriber may subscribe or unsubscribe while the event runs; the
   // event goes to those subscribed when it arrived.
   for (const subscriber of [...channel.subscribers]) {
@@ -137,7 +172,9 @@ function dispatch(channel: Channel, event: Event): void {
       continue;
     }
     try {
-      subscriber.listener(event);
+      if (subscriber.listener(event) === true && subscriber.isFirst) {
+        return;
+      }
     } catch (error) {
       report(error);
     }

package/src/utils/interactionOverlay.stylex.ts

@@ -9,7 +9,8 @@
  * @input StyleX and the semantic interaction-overlay color tokens
  * @output Reusable background-color and background-image state styles, the
  *   touch press's registered strength variable (`pressVars`) and its clocks
- *   (`pressConsts`)
+ *   (`pressConsts`). The list row's compositor press layer and its clocks
+ *   are internal (privateAttributes/press.stylex.ts, utils/rowPressLayer.stylex.ts)
  * @position Internal styling utility for interactive core surfaces
  *
  * SYNC: When modified, update pressFeedback.ts, pressGesture.ts (the fade
@@ -148,7 +149,11 @@ const pressRelease = stylex.keyframes({
  * (strength ≈ 0.2 at the midpoint), which is what a deselect crossfade reads
  * as. Not the system's `--ease-standard`: that curve is for things that move,
  * and is so front-loaded (strength 0.05 at the midpoint) that the release
- * would read as half its clock.
+ * would read as half its clock. It is the constants table's
+ * `timing.press.highlightOutCurve`, which the list row's layer mirrors too
+ * (rowPressLayer.stylex.ts); interactionOverlay.cell.test.ts fails if either
+ * drifts. A copy, not an import: this module reaches nearly every component,
+ * and the row layer's constants stay with the rows.
  */
 const RELEASE_EASE = 'cubic-bezier(0, 0, 0.2, 1)';