@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/dist/hooks/ModalAnnounceProvider.js

@@ -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
@@ -18,6 +18,7 @@ import { use, useEffect, useMemo, useRef } from 'react';
 import { forgetPresented, handOffUnexposed, isExposed, notePresented, releaseAllHeld } from "./modalAnnounce.js";
 import { ModalAnnounceContext } from "./useAnnounce.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+import { observeMutations } from "../utils/sharedMutationObserver.js";
 
 /**
  * Rendered by every Astryx component that owns a native `<dialog>` (Dialog,
@@ -54,12 +55,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(null);
   useEffect(() => {
     const dialog = dialogRef.current;
@@ -72,11 +71,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
@@ -101,11 +100,12 @@ export function ModalAnnounceProvider({
         end();
       }
     };
-    const presentation = new MutationObserver(onPresentationChange);
-    presentation.observe(dialog, {
+    // 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

package/dist/hooks/actionGroupTracker.d.ts

@@ -93,6 +93,18 @@ export interface ActionGroupTracker {
 /**
  * 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 declare function createActionGroupTracker(getOptions: () => ActionGroupTrackerOptions): ActionGroupTracker;
 //# sourceMappingURL=actionGroupTracker.d.ts.map

package/dist/hooks/actionGroupTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actionGroupTracker.d.ts","sourceRoot":"","sources":["../../src/hooks/actionGroupTracker.ts"],"names":[],"mappings":"AAgEA,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,KAAK,EAAE,MAAM,QAAQ,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClD,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,QAAQ,EAAE,WAAW,GAAG,IAAI,KACzB,IAAI,CAAC;IACV,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACzC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CACd,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,KACtC,WAAW,GAAG,IAAI,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI,CAAC;IAC/D,2CAA2C;IAC3C,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;;OAKG;IACH,GAAG,IAAI,WAAW,GAAG,IAAI,CAAC;IAC1B,+EAA+E;IAC/E,MAAM,IAAI,IAAI,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AA0DD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,yBAAyB,GAC1C,kBAAkB,CA8NpB"}
+{"version":3,"file":"actionGroupTracker.d.ts","sourceRoot":"","sources":["../../src/hooks/actionGroupTracker.ts"],"names":[],"mappings":"AAoBA,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,KAAK,EAAE,MAAM,QAAQ,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClD,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,QAAQ,EAAE,WAAW,GAAG,IAAI,KACzB,IAAI,CAAC;IACV,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACzC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CACd,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,KACtC,WAAW,GAAG,IAAI,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI,CAAC;IAC/D,2CAA2C;IAC3C,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;;OAKG;IACH,GAAG,IAAI,WAAW,GAAG,IAAI,CAAC;IAC1B,+EAA+E;IAC/E,MAAM,IAAI,IAAI,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC;IAClB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AA0DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,yBAAyB,GAC1C,kBAAkB,CA8NpB"}

package/dist/hooks/actionGroupTracker.js

@@ -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
  */
@@ -65,11 +21,11 @@ const DISABLED = ':disabled, [aria-disabled="true"]';
 /** A target the tracker measured: its element and viewport rect, px. */
 
 /**
- * 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) {
   const disarm = () => {
@@ -115,6 +71,18 @@ function clickAndReport(element) {
 /**
  * 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) {
   let actions = [];

package/dist/hooks/menuPressGesture.d.ts

@@ -1,32 +1,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
@@ -113,6 +91,23 @@ export interface MenuPressStep<T> {
 export declare const IDLE_MENU_PRESS: MenuPressGesture<never>;
 /**
  * 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 declare function menuPressStep<T>(gesture: MenuPressGesture<T>, event: MenuPressEvent<T>): MenuPressStep<T>;
 //# sourceMappingURL=menuPressGesture.d.ts.map

package/dist/hooks/menuPressGesture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menuPressGesture.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressGesture.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GACf;IACE,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,oBAAoB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,oBAAoB,CAAC;IAClC,6BAA6B;IAC7B,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,WAAW,EAAE,oBAAoB,CAAC;IAClC,qEAAqE;IACrE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AACH,6DAA6D;GAC3D;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9D;IACE,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AACH,+EAA+E;GAC7E;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAC;AAErB,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC;AAChB,8EAA8E;GAC5E;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACd;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,GACf;IAAC,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC;AACvB;;;;GAIG;GACD;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAAC;AAEvD,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC5B;AAED,eAAO,MAAM,eAAe,EAAE,gBAAgB,CAAC,KAAK,CAAmB,CAAC;AA+BxE;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB,aAAa,CAAC,CAAC,CAAC,CAWlB"}
+{"version":3,"file":"menuPressGesture.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressGesture.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GACf;IACE,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,oBAAoB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,oBAAoB,CAAC;IAClC,6BAA6B;IAC7B,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,WAAW,EAAE,oBAAoB,CAAC;IAClC,qEAAqE;IACrE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AACH,6DAA6D;GAC3D;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9D;IACE,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AACH,+EAA+E;GAC7E;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAC;AAErB,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC;AAChB,8EAA8E;GAC5E;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACd;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,GACf;IAAC,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC;AACvB;;;;GAIG;GACD;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAAC;AAEvD,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC5B;AAED,eAAO,MAAM,eAAe,EAAE,gBAAgB,CAAC,KAAK,CAAmB,CAAC;AA+BxE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB,aAAa,CAAC,CAAC,CAAC,CAWlB"}

package/dist/hooks/menuPressGesture.js

@@ -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
@@ -89,6 +67,23 @@ function release(pointerType, event) {
 
 /**
  * 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(gesture, event) {
   switch (gesture.phase) {
@@ -161,10 +156,10 @@ function stepTriggerPress(gesture, event) {
         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,

package/dist/hooks/menuPressMarker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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 declare const MENU_PRESS_MARKER = "data-astryx-menu-press";
+//# sourceMappingURL=menuPressMarker.d.ts.map

package/dist/hooks/menuPressMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menuPressMarker.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressMarker.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,2BAA2B,CAAC"}

package/dist/hooks/menuPressMarker.js

@@ -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/dist/hooks/menuPressOnItems.d.ts

@@ -1,18 +1,11 @@
 /**
  * @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.
  */
 import type { PointerEvent as ReactPointerEvent } from 'react';
 export declare function pressOnItemsOnly<E extends HTMLElement>(onPointerDown: (event: ReactPointerEvent<E>) => void, itemSelector: string): (event: ReactPointerEvent<E>) => void;

package/dist/hooks/menuPressOnItems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menuPressOnItems.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressOnItems.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAC,YAAY,IAAI,iBAAiB,EAAC,MAAM,OAAO,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,EACpD,YAAY,EAAE,MAAM,GACnB,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,CAevC"}
+{"version":3,"file":"menuPressOnItems.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressOnItems.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAC,YAAY,IAAI,iBAAiB,EAAC,MAAM,OAAO,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,EACpD,YAAY,EAAE,MAAM,GACnB,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,CAevC"}

package/dist/hooks/menuPressOnItems.js

@@ -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.
+
 export function pressOnItemsOnly(onPointerDown, itemSelector) {
   return event => {
     const target = event.target;

package/dist/hooks/modalAnnounce.d.ts

@@ -12,7 +12,7 @@ export declare function releaseAllHeld(): void;
  * 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 declare function handOffUnexposed(dialog: HTMLDialogElement): void;
 //# sourceMappingURL=modalAnnounce.d.ts.map

package/dist/hooks/modalAnnounce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modalAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/modalAnnounce.ts"],"names":[],"mappings":"AA6CA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAM5D;AAyBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAQ7D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAK/D;AA0JD,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AA4BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAQhE"}
+{"version":3,"file":"modalAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/modalAnnounce.ts"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAM5D;AAyBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAQ7D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAK/D;AAuJD,wBAAgB,cAAc,IAAI,IAAI,CAIrC;AA4BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAQhE"}

package/dist/hooks/modalAnnounce.js

@@ -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.
  */
@@ -130,14 +118,11 @@ function isAnyModalOpen() {
   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.
 
 const held = new Map();
 
@@ -240,7 +225,7 @@ function deliverBeyond(dialog, message, politeness) {
  * 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) {
   for (const politeness of ['polite', 'assertive']) {
@@ -293,11 +278,10 @@ function announceInModalRouted(dialog, message, politeness = 'polite') {
   });
 }
 
-// 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.
 
 const deferredByScope = new WeakMap();
 function deferUntilPresented(scope, message, politeness) {
@@ -395,15 +379,12 @@ function isBeingPresented(scope) {
  */
 function announceFromScope(scope, message, politeness) {
   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/dist/hooks/scrollbarGutter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CA+D7E"}
+{"version":3,"file":"scrollbarGutter.d.ts","sourceRoot":"","sources":["../../src/hooks/scrollbarGutter.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;IACf,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CA+D7E"}

package/dist/hooks/scrollbarGutter.js

@@ -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 = {
   settle() {},
   release() {}

package/dist/hooks/useAnimatedLayout.d.ts

@@ -3,8 +3,7 @@
  * @input React (useMemo), motion/animatedLayout.ts
  * @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle
  *   type
- * @position Public hook (`spec:AST-105`) over the one size-change module
- *   (`architecture:react-component-runtime` INV12)
+ * @position Public hook over the one size-change module
  *
  * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
  */
@@ -24,7 +23,7 @@ export interface UseAnimatedLayoutOptions {
  *
  * `containerRef` names the area: an app passes the ref it already gives its
  * scroll container or panel (a ScrollableArea's ref reaches its native scroll
- * viewport). The handle has no public members (`spec:AST-105` FR1).
+ * viewport). The handle has no public members.
  *
  * @example
  * ```

package/dist/hooks/useAnimatedLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAnimatedLayout.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnimatedLayout.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,GACb,EAAE,wBAAwB,GAAG,cAAc,CAO3C"}
+{"version":3,"file":"useAnimatedLayout.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnimatedLayout.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,YAAY,GACb,EAAE,wBAAwB,GAAG,cAAc,CAO3C"}