@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/gestures/usePressTracker.ts

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file usePressTracker.ts
+ * @input An element ref and press tracker options
+ * @output Exports usePressTracker
+ * @position React face of packages/core/src/gestures' PressTracker, in its
+ *   own module so a component that only recognizes gestures never imports
+ *   the press tracker
+ *
+ * The callbacks and the profile are read through refs: one tracker serves
+ * the component's life, so a profile change applies from the tracker's next
+ * read and never ends a press in progress. After unmount the tracker calls
+ * nothing back.
+ *
+ * SYNC: When modified, update useGestureRecognizer.test.tsx and README.md.
+ */
+
+import {useMemo, useRef, useState, type RefObject} from 'react';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {UIKIT_CONTROL} from '../motion/uikit/gestures';
+import {getGestureHost} from './GestureHost';
+import {
+  createPressTracker,
+  vetoesSingleTap,
+  type PressTracker,
+  type PressTrackerOptions,
+} from './PressTracker';
+import {useAttachment} from '../hooks/useAttachment';
+import {
+  isSyncingGestures,
+  syncingGestures,
+  useIsUnmountedRef,
+} from './gestureSync';
+
+export type UsePressTrackerOptions = Omit<
+  PressTrackerOptions,
+  'getBounds' | 'view'
+> & {
+  /**
+   * Accepted and ignored: every attachment reads each event's pointer
+   * (`spec:AST-094` FR43). Kept so callers written before FR43 compile.
+   * @deprecated
+   */
+  perEventPointer?: boolean;
+};
+
+/**
+ * Track presses on the element behind `ref` with UIControl semantics. The
+ * callbacks are read through a ref, like a recognizer's listener. Releasing
+ * the element (unmount, or a replaced node) ends any press without calling
+ * them: that release runs in an Effect, which never calls a caller's
+ * callback (react-component-runtime INV2, INV3).
+ */
+export function usePressTracker(
+  ref: RefObject<Element | null>,
+  options: UsePressTrackerOptions = {},
+): PressTracker {
+  const optionsRef = useRef(options);
+  // True while an Effect releases the tracker, so the press it ends reaches
+  // no caller callback.
+  const isReleasingRef = useRef(false);
+  // The ref is read through a ref too: a caller may pass a new ref object
+  // on a render, and the one tracker must follow it.
+  const refRef = useRef(ref);
+  // Syncs the options and ref refs with the newest render.
+  useIsomorphicLayoutEffect(() => {
+    optionsRef.current = options;
+    refRef.current = ref;
+  });
+  const isUnmountedRef = useIsUnmountedRef();
+  const {perEventPointer = false} = options;
+  // Calls a caller callback: never while an Effect releases the tracker or
+  // after unmount. While any gesture hook's isEnabled sync runs (turning off
+  // a recognizer the press waits on resolves the press in that arena pass,
+  // inside the Effect), the call waits for a microtask after it, in order,
+  // so the press still ends, un-highlighted, outside the Effect
+  // (react-component-runtime INV2).
+  const [deliver] = useState(() => (call: () => void) => {
+    if (isReleasingRef.current || isUnmountedRef.current) {
+      return;
+    }
+    if (!isSyncingGestures()) {
+      call();
+      return;
+    }
+    queueMicrotask(() => {
+      if (!isUnmountedRef.current) {
+        call();
+      }
+    });
+  });
+  // One tracker for the component's life, reading its profile through the
+  // options ref: a profile change never rebuilds it, so a press in progress
+  // survives it (the change applies from the tracker's next read).
+  // `keepsTouch` is the exception, fixed when the tracker is created: it
+  // decides whether the host gives the element a blocking touchmove.
+  const [tracker] = useState(() =>
+    createPressTracker({
+      getBounds: () => {
+        const element = refRef.current.current;
+        return element == null
+          ? null
+          : getGestureHost(element.ownerDocument).presentedRect(element);
+      },
+      get view() {
+        return refRef.current.current;
+      },
+      onControlEvent: (event, touch) =>
+        deliver(() => optionsRef.current.onControlEvent?.(event, touch)),
+      onHighlightChange: isHighlighted =>
+        deliver(() => optionsRef.current.onHighlightChange?.(isHighlighted)),
+      trackingExpansion: options.trackingExpansion,
+      get highlightDelay() {
+        return optionsRef.current.highlightDelay;
+      },
+      get cancelTravel() {
+        return optionsRef.current.cancelTravel;
+      },
+      get quickTapFlash() {
+        return optionsRef.current.quickTapFlash;
+      },
+      keepsTouch: options.keepsTouch,
+      get selectionLock() {
+        return optionsRef.current.selectionLock;
+      },
+      // The caller's veto, read on every touch, else the tracker's own.
+      vetoesAncestorRecognizer: recognizer =>
+        (optionsRef.current.vetoesAncestorRecognizer ?? vetoesSingleTap)(
+          recognizer,
+        ),
+      isEnabled: () => optionsRef.current.isEnabled?.() ?? true,
+      // The caller's brake, or the host's: a touch that stops a flick
+      // presses nothing, as a UIKit control in a decelerating scroll view.
+      isBraking: touch => {
+        const own = optionsRef.current.isBraking;
+        if (own != null) {
+          return own(touch);
+        }
+        const element = refRef.current.current;
+        return (
+          element != null &&
+          getGestureHost(element.ownerDocument).isScrollBraking(element)
+        );
+      },
+    }),
+  );
+  const {trackingExpansion} = options;
+  // Syncs the tracker's tracking expansion with the option.
+  useIsomorphicLayoutEffect(() => {
+    tracker.trackingExpansion =
+      trackingExpansion ?? UIKIT_CONTROL.trackingExpansion.value;
+  }, [tracker, trackingExpansion]);
+
+  // Syncs the host's press consumer with the element behind `ref`.
+  // Releasing the element (a replaced node, unmount) disposes the press,
+  // which un-highlights a control it was holding.
+  const attachment = useMemo(
+    () => ({tracker, perEventPointer}),
+    [tracker, perEventPointer],
+  );
+  useAttachment(
+    ref,
+    element => {
+      const detach = getGestureHost(element.ownerDocument).attachConsumer(
+        element,
+        attachment.tracker,
+        {perEventPointer: attachment.perEventPointer},
+      );
+      return () => {
+        isReleasingRef.current = true;
+        try {
+          detach();
+          tracker.dispose();
+        } finally {
+          isReleasingRef.current = false;
+        }
+      };
+    },
+    attachment,
+  );
+
+  // Syncs the host's listeners with the tracker's enabled state, which can
+  // change with any render: the host listens only while an enabled control
+  // is attached (spec:AST-094 FR24). A control disabled under a finger ends
+  // that press here, inside the release guard: a disabled control tracks no
+  // touch, and this Effect calls back no caller, whether the host stops
+  // listening or another control keeps it listening.
+  useIsomorphicLayoutEffect(() => {
+    const element = refRef.current.current;
+    isReleasingRef.current = true;
+    try {
+      if (tracker.isTracking && !(optionsRef.current.isEnabled?.() ?? true)) {
+        tracker.dispose();
+      }
+      if (element != null) {
+        // The update's arena pass can settle other recognizers and trackers
+        // too: it runs as a gesture sync, so none calls its caller back from
+        // this Effect.
+        syncingGestures(() =>
+          getGestureHost(element.ownerDocument).update(element),
+        );
+      }
+    } finally {
+      isReleasingRef.current = false;
+    }
+  });
+
+  return tracker;
+}

package/src/hooks/ModalAnnounceProvider.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file ModalAnnounceProvider.tsx
- * @input Uses React context, effects and the exposure and delivery
- *   internals of useAnnounce
+ * @input Uses React context, effects, the exposure and delivery internals of
+ *   useAnnounce, and the shared MutationObserver
  * @output Exports ModalAnnounceProvider, the element every Astryx component
  *   that owns a native <dialog> renders around its content
  * @position Core a11y internal (spec:AST-086 FR14). Its own module so only
@@ -32,6 +32,7 @@ import {
 } from './modalAnnounce';
 import {ModalAnnounceContext, type ModalAnnounceScope} from './useAnnounce';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+import {observeMutations} from '../utils/sharedMutationObserver';
 
 /**
  * Rendered by every Astryx component that owns a native `<dialog>` (Dialog,
@@ -56,10 +57,9 @@ export function ModalAnnounceProvider({
 }: {
   dialogRef: RefObject<HTMLDialogElement | null>;
   /**
-   * The owner's intent for this render: open as a modal (or presented as a
-   * modal step). A non-modal surface — a scrimless Drawer shown with
-   * `showPopover()`, a scrimless sheet — passes `false`: it is not an FR14
-   * modal, and callers inside it route as the page does.
+   * The owner's intent for this render: open as a modal, or presented as a
+   * modal step. A non-modal surface, such as a scrimless Drawer or sheet,
+   * passes `false`. Callers inside it route as the page does.
    */
   isOpen: boolean;
   children: ReactNode;
@@ -76,12 +76,10 @@ export function ModalAnnounceProvider({
   useIsomorphicLayoutEffect(() => {
     scope.isOpen = isOpen;
   }, [scope, isOpen]);
-  // The presentation watch is a session: it starts when the owner intends
-  // the dialog open (or finds it already open), follows `open`, `inert` and
-  // `aria-hidden` through the exit, and ends once the dialog has really
-  // closed, or when the provider unmounts. A closed dialog at rest — a
-  // preloaded sheet, a Drawer never shown — holds no observer
-  // (`architecture:react-component-runtime` INV5).
+  // The presentation watch is a session. It starts when the owner intends the
+  // dialog open, or finds it open. It follows `open`, `inert` and
+  // `aria-hidden` through the exit, and it ends when the dialog really closes
+  // or the provider unmounts. A closed dialog at rest holds no observer.
   const sessionRef = useRef<{
     dialog: HTMLDialogElement;
     stop: () => void;
@@ -97,11 +95,11 @@ export function ModalAnnounceProvider({
     notePresented(dialog);
     let wasOpen = dialog.open;
     const end = () => {
-      presentation.disconnect();
+      stop();
       forgetPresented(dialog);
       sessionRef.current = null;
     };
-    const stop = () => presentation.disconnect();
+    const stop = () => unobserve();
     const onPresentationChange = () => {
       // The order is the top-layer order: only `open` being set moves a
       // dialog up it. A dialog turning inert or aria-hidden for its exit
@@ -126,11 +124,13 @@ export function ModalAnnounceProvider({
         end();
       }
     };
-    const presentation = new MutationObserver(onPresentationChange);
-    presentation.observe(dialog, {
-      attributes: true,
-      attributeFilter: ['open', 'inert', 'aria-hidden'],
-    });
+    // Core's shared observer watches every open modal's presentation: one
+    // observer for all of them, not one per open modal.
+    const unobserve = observeMutations(
+      dialog,
+      {attributes: true, attributeFilter: ['open', 'inert', 'aria-hidden']},
+      onPresentationChange,
+    );
     sessionRef.current = {dialog, stop};
   }, [dialogRef, isOpen]);
   useEffect(

package/src/hooks/actionGroupTracker.ts

@@ -2,56 +2,12 @@
 
 /**
  * @file actionGroupTracker.ts
- * @input The elements whose actions are tracked, the actions' selector and
- *   hit expansion, and the press paint and fade clocks
- * @output Exports createActionGroupTracker, ActionGroupTracker,
- *   ActionGroupTrackerOptions and ActionGroupTarget: UIKit's tracking of a
- *   held finger across a group of targets, as a plain object any gesture
- *   recognizer can drive
- * @position The one tracker for a held finger that slides onto an action,
- *   internal to core. Gesture recognizers drive it: an alert's or an action
- *   sheet's long press on its group of actions, a menu trigger whose held
- *   finger slides into the menu it opened, a menu's list, a segmented
- *   control's segments, a page control's dots
- *
- * UIKit tracks a group of actions (an alert's, an action sheet's, a menu's)
- * as one control, not as separate buttons (measured on iOS 26.2):
- *
- * - the action under the finger highlights; sliding off it cuts its highlight
- *   and sliding onto another highlights that one; between or outside the
- *   actions nothing is highlighted;
- * - lifting runs the action under the finger, and nothing when there is none;
- *   the lifted action's highlight fades (PRESS_FADE_MS);
- * - a press the owner calls inert (an alert during its transitions) is taken
- *   but paints and runs nothing.
- *
- * Which target a finger is on is the hit test above by default; an owner
- * whose targets are a row of segments or dots resolves it itself
- * (`resolveTarget`: the nearest segment along the axis, the end one past the
- * ends), from the same rects. The finger's raw position reaches `onMove`
- * (a lens that chases it), and an owner that shows the highlight another way
- * (focus, a dimmed title) turns the paint off and follows
- * `onHighlightChange(next, previous)`.
- *
- * Nothing reads layout after a press begins: the actions' rects are read once
- * in `begin`, then hit-tested; `offsetBy` shifts them when the content moves
- * under a still finger (autoscroll). A move costs at most two attribute writes
- * and never a render. The action runs through its own `click()` inside `end`,
- * so the recognizer must call `end` from the lift's event (its touchend): that
- * keeps the user activation and every click handler. `onActivated` learns
- * whether a handler cancelled that click (`preventDefault()` vetoes, and the
- * owner can undo its visual at once). A recognizer that does not claim the
- * touch leaves the browser its own click for it; `swallowsNativeClick` takes
- * that one click, so the action runs exactly once (the swallower listens only
- * from that lift until the click, or the next press or key).
- *
- * This is core's one track-across-items loop. Menus still run their own copy
- * of it in useMenuPress.ts; the change after the in-flight menu press work
- * moves that copy here, and useMenuPress keeps only its menu-only parts (a
- * trigger's press or held finger opening the menu, the settle rule, edge
- * autoscroll, the highlight as DOM focus). Add no third copy meanwhile.
- * Nothing in core drives this tracker yet; its first adopters (the segmented
- * control and the action groups) arrive in their own changes.
+ * @input The tracked elements, the action selector and hit expansion, and the
+ *   press paint and fade clocks
+ * @output createActionGroupTracker, ActionGroupTracker,
+ *   ActionGroupTrackerOptions, ActionGroupTarget
+ * @position Internal core tracker for a held finger that slides across a
+ *   group of actions. Gesture recognizers drive it.
  *
  * SYNC: When modified, update actionGroupTracker.test.ts
  */
@@ -171,11 +127,11 @@ interface TrackedAction {
 }
 
 /**
- * The browser's own click for a touch the lift already acted on: swallowed
- * once, by listeners that exist only from that lift until the click, or the
- * next press or key (whichever comes first). An activation with
- * `detail === 0` (a key, assistive technology) is not that click: it always
- * passes, and the swallower keeps waiting (`spec:AST-094` FR21).
+ * Swallow the browser's own click for a touch that the lift already acted
+ * on. The listeners exist only from that lift until the click, the next
+ * press, or the next key. An activation with `detail === 0` (a key or
+ * assistive technology) always passes, and the swallower keeps waiting
+ * (`AST-094`).
  */
 function swallowNextClick(view: Window): void {
   const disarm = () => {
@@ -221,6 +177,18 @@ function clickAndReport(element: HTMLElement): boolean {
 /**
  * Create a tracker. `getOptions` is read on every call, so a hook can pass
  * the latest props without recreating it.
+ *
+ * The tracker treats a group of actions as one control, as UIKit does:
+ * - The action under the finger highlights. Between or outside the actions,
+ *   nothing highlights.
+ * - The lift runs the action under the finger, and its highlight fades.
+ * - An inert press is taken but paints and runs nothing.
+ *
+ * Layout is read only in `begin`. `offsetBy` shifts the cached rects when
+ * the content moves under a still finger. The action runs through its own
+ * `click()` in `end`, so call `end` from the lift's event to keep the user
+ * activation. useMenuPress.ts has its own copy of this loop. Do not add a
+ * third copy.
  */
 export function createActionGroupTracker(
   getOptions: () => ActionGroupTrackerOptions,

package/src/hooks/menuPressGesture.ts

@@ -3,32 +3,10 @@
 /**
  * @file menuPressGesture.ts
  * @input A menu press gesture and one pointer event, both as plain data
- * @output Exports the pure `menuPressStep` state machine, its state, event and
- *   effect types, and the settle constant
- * @position Pure module under `useMenuPress`; no DOM, no React, so every
- *   transition is unit-testable without a browser
- *
- * The press model shared by every Astryx menu and picker: the row under the
- * pointer when it is RELEASED is the row that acts, and the highlight follows
- * the pointer while it is held. It is the model of macOS and iOS menus.
- *
- * States:
- * - `idle` — no gesture is live.
- * - `triggerPress` — a finger rests on the trigger; the menu is not open yet.
- *   A mouse skips this state: a mouse press on the trigger opens at once.
- * - `open` — the menu opened under a held pointer (a mouse press, or a finger
- *   held for the long-press delay) and the pointer has not entered it yet.
- * - `tracking` — the pointer is held and the highlight follows it.
- *
- * The settle rule: the release of the gesture that OPENED the menu acts only
- * once the pointer has entered the menu or the press has lasted
- * `MENU_PRESS_SETTLE_MS`; otherwise it acts on nothing and the menu stays
- * open. Without it a menu that opens under the pointer would pick a row
- * nobody chose.
- *
- * Rows are opaque (`T`): the machine never touches the DOM. The hook resolves
- * the enabled row under the pointer and feeds it in; `null` means the pointer
- * is over a divider, a heading, a disabled row, or outside the menu.
+ * @output The pure `menuPressStep` state machine, its state, event and effect
+ *   types, and the settle constant
+ * @position Pure module under `useMenuPress`. It has no DOM and no React, so
+ *   a unit test can check each transition without a browser.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/menuPressGesture.test.ts
@@ -135,6 +113,23 @@ function release<T>(
 
 /**
  * Advance the gesture by one event. Pure: same inputs, same output.
+ *
+ * The row under the pointer at the release acts, and the highlight follows
+ * the held pointer, as in macOS and iOS menus. The states:
+ * - `idle`: no gesture is live.
+ * - `triggerPress`: a finger rests on the trigger, and the menu is not open
+ *   yet. A mouse press on the trigger skips this state and opens at once.
+ * - `open`: the menu opened under a held pointer, and the pointer has not
+ *   entered it yet.
+ * - `tracking`: the pointer is held, and the highlight follows it.
+ *
+ * The settle rule: the release of the opening gesture acts only after the
+ * pointer entered the menu or the press lasted `MENU_PRESS_SETTLE_MS`. Else a
+ * menu that opens under the pointer would pick a row that nobody chose.
+ *
+ * Rows are opaque (`T`). The hook feeds in the enabled row under the
+ * pointer, or `null` over a divider, a heading, a disabled row, or outside
+ * the menu.
  */
 export function menuPressStep<T>(
   gesture: MenuPressGesture<T>,
@@ -209,10 +204,10 @@ function stepTriggerPress<T>(
       // it must pass, and no gesture is live afterwards.
       return idle({type: 'settle', stray: false, dismiss: false});
     case 'cancel':
-      // The browser took the gesture (an incoming call, a system gesture).
-      // Settle rather than going quiet: a held finger has already installed
-      // the document's touchmove preventer, and only the end of a gesture
-      // takes it back off. No click follows a cancelled pointer.
+      // The browser took the gesture, for example for a system gesture.
+      // Settle and do not go idle: a held finger installed the document's
+      // touchmove preventer, and only the end of a gesture removes it. No
+      // click follows a cancelled pointer.
       return idle({type: 'settle', stray: false, dismiss: false});
     case 'down':
     case 'move':

package/src/hooks/menuPressMarker.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuPressMarker.ts
+ * @input None (a plain attribute-name constant)
+ * @output Exports MENU_PRESS_MARKER
+ * @position Dependency-free home of the public menu-press marker, so the press
+ *   feedback controller (utils/pressFeedback.ts) can read it without loading
+ *   the menu-press hook into every pressable component's bundle.
+ *   useMenuPress.ts re-exports it; the public path stays
+ *   `@astryxdesign/core/hooks`.
+ */
+
+/** Marks a menu root that carries the menu press model (useMenuPress). */
+export const MENU_PRESS_MARKER = 'data-astryx-menu-press';

package/src/hooks/menuPressOnItems.ts

@@ -3,20 +3,18 @@
 /**
  * @file menuPressOnItems.ts
  * @input useMenuPress's menu `onPointerDown` and the menu's item selector
- * @output Exports pressOnItemsOnly: the same handler, run only for a press
- *   that lands on an item and is not a modified mouse press on a link
+ * @output pressOnItemsOnly: the same handler, run only for a press that lands
+ *   on an item and is not a modified mouse press on a link
  * @position Internal to core's menus with caller content or link items
  *   (NavHeadingMenu, TopNavMenu, SideNavHeading's and TopNavHeading's menus,
  *   BreadcrumbItem's menu)
- *
- * A menu that holds caller content beside its items (a button, a link list)
- * tracks only presses that land on an item. A press on anything else stays
- * the browser's own, so that content's click runs as it always has
- * (`architecture:interaction-modality` INV4). A mouse press with Ctrl, Cmd or
- * Shift on a link item is the browser's too, so it opens the link in a new
- * tab or window as it always has; a middle press never reaches the model.
  */
 
+// A press on caller content beside the items stays the browser's, so that
+// content's click runs as before. A Ctrl, Cmd or Shift mouse press on a link
+// item also stays the browser's, so it opens the link in a new tab or window.
+// A middle press never reaches the model.
+
 import type {PointerEvent as ReactPointerEvent} from 'react';
 
 export function pressOnItemsOnly<E extends HTMLElement>(

package/src/hooks/modalAnnounce.ts

@@ -4,23 +4,11 @@
 
 /**
  * @file modalAnnounce.ts
- * @input Uses the live-region internals of useAnnounce and DOM dialog state
+ * @input The live-region internals of useAnnounce and DOM dialog state
  * @output Installs the modal route into useAnnounce as it loads, and exports
- *   the presentation bookkeeping ModalAnnounceProvider drives
- * @position Core a11y internal (spec:AST-086 FR14): where a message from
- *   inside an Astryx modal is heard. A dialog is exposed when it is open as
- *   a modal and neither inert nor aria-hidden; the top-layer order is kept
- *   by `open` alone; a message a dialog holds when it stops being exposed is
- *   handed to the channel exposed then, or held while an exiting modal still
- *   covers everything, and released at its real close; a covered modal is
- *   not written to; a caller inside a modal being presented in this commit
- *   waits one frame for the route. Words move with their announcers'
- *   receipts, one delivery per announcer, so an announcer can take back its
- *   own share while it waits wherever it went: a `hasReplace` instance's
- *   next message (FR9), a busy start overtaken by its outcome (FR8). Loaded
- *   only by ModalAnnounceProvider, so
- *   a component that calls useAnnounce and renders no modal does not carry
- *   it.
+ *   the presentation bookkeeping that ModalAnnounceProvider drives
+ * @position Core a11y internal (AST-086 FR14) that decides where a message
+ *   from inside an Astryx modal is heard. Only ModalAnnounceProvider loads it.
  *
  * SYNC: not exported from /packages/core/src/hooks/index.ts.
  */
@@ -157,14 +145,11 @@ function isAnyModalOpen(): boolean {
   return false;
 }
 
-// Words waiting for an exiting modal's real close: their dialog has left
-// the accessibility tree for its exit but is still an open native modal, or
-// such a dialog covers the channel they would go to, so nothing is exposed
-// yet. They are delivered when a dialog closes (or theirs is exposed again).
-// Each text keeps its announcers' receipts, so one taking its share back
-// leaves it for the others, and a receipt follows the words when they are
-// released; an entry is gone once delivered, so a receipt never reaches
-// equal words held later.
+// Words that wait for an exiting modal's real close. Their dialog left the
+// accessibility tree for its exit but is still an open native modal, or such
+// a dialog covers their channel. They are delivered when a dialog closes or
+// theirs is exposed again. Each text keeps its announcers' receipts. An entry
+// is gone once delivered, so a receipt never reaches equal words held later.
 interface HeldWords extends WaitingWords {
   readonly receipts: AnnounceReceipt[];
 }
@@ -285,7 +270,7 @@ function deliverBeyond(
  * Move whatever `dialog`'s containers hold that assistive technology has not
  * had yet to the channel exposed now. Called when the dialog stops being
  * exposed — closed, taken inert or `aria-hidden` for its exit, or unmounted
- * while open — so a message sent just before is not lost (FR14).
+ * while open — so a message sent just before is not lost.
  */
 export function handOffUnexposed(dialog: HTMLDialogElement): void {
   for (const politeness of ['polite', 'assertive'] as const) {
@@ -352,11 +337,10 @@ function announceInModalRouted(
   });
 }
 
-// Messages from callers whose enclosing modal is being presented in this
-// commit, waiting one frame for the route; an empty message among them
-// withdraws the earlier ones of its urgency, as it would on a channel.
-// Each message keeps a receipt per announcer: before the frame, taking it
-// back drops that announcer's share; the frame points it at its write.
+// Messages from callers whose modal is presented in this commit wait one
+// frame for the route. An empty message among them withdraws the earlier
+// ones of its urgency. Before the frame, a receipt drops its announcer's
+// share. The frame points the receipt at its write.
 interface Deferred {
   frame: number;
   words: Record<AnnouncePoliteness, HeldWords[]>;
@@ -462,15 +446,12 @@ function announceFromScope(
   politeness: AnnouncePoliteness,
 ): WithdrawAnnouncement | null {
   if (isBeingPresented(scope)) {
-    // Announced in the commit that opens the enclosing modal — a field error
-    // inside `{isOpen && <Dialog isOpen>}`, alone or inside an already-open
-    // Dialog — before the Dialog's own Effect, which runs after its
-    // content's, has called showModal(). Choose the route a frame later,
-    // when it has, rather than the modal beneath, which the new one is about
-    // to cover; an empty message in the same commit withdraws what waits
-    // (FR9). A caller inside a modal that is meant to be closed (its content
-    // stays mounted) is not waiting for anything: it takes the route of
-    // where it is now, joined with the frame's other messages.
+    // The message comes in the commit that opens its modal, before the
+    // Dialog's Effect calls showModal(), because that Effect runs after its
+    // content's. Choose the route a frame later, not the modal beneath that
+    // the new one will cover. An empty message in the same commit withdraws
+    // what waits. A caller in a modal that is meant to be closed waits for
+    // nothing: it takes the route of where it is now.
     return deferUntilPresented(scope, message, politeness);
   }
   const dialog = enclosingOpenModal(scope);

package/src/hooks/scrollbarGutter.ts

@@ -3,26 +3,19 @@
 /**
  * @file scrollbarGutter.ts
  * @input The element a scroll lock pins, plus live layout measurements
- * @output Exports holdScrollbarGutter and the ScrollbarGutterHold it returns
+ * @output holdScrollbarGutter and the ScrollbarGutterHold it returns
  * @position Internal hook utility; used by useScrollLock and MobileNav so that
  *   locking background scroll does not resize the layout viewport.
- *
- * Locking scroll hides the document's scrollbar. Where that scrollbar is a
- * classic (space-taking) one — Windows/Linux desktop, and macOS set to
- * "Always" show scroll bars — hiding it widens the layout viewport by the
- * scrollbar's width and the whole page jumps sideways behind the overlay.
- *
- * The fix is `scrollbar-gutter: stable`, which holds the gutter open once the
- * scrollbar goes away. Being a real layout change it holds `position: fixed`
- * chrome (sticky headers, toast viewports) as well as in-flow content, which
- * padding fundamentally cannot: fixed elements resolve against the viewport,
- * not against the padded element.
- *
- * Padding is kept only as a fallback for engines without `scrollbar-gutter`
- * (Safari shipped it in 18.2), and it is applied by measuring whether the
- * element actually moved rather than by assuming it did.
  */
 
+// A scroll lock hides the document's scrollbar. A classic, space-taking
+// scrollbar then gives its width back, and the page jumps sideways behind the
+// overlay. `scrollbar-gutter: stable` keeps the gutter open. It is a layout
+// change, so it also holds `position: fixed` chrome, which padding cannot:
+// fixed elements resolve against the viewport. Padding is only a fallback for
+// engines without `scrollbar-gutter`, and it applies only when a measurement
+// shows that the element moved.
+
 const NOOP: ScrollbarGutterHold = {
   settle() {},
   release() {},