@jsenv/navi 0.29.68 → 0.29.69

package/dist/jsenv_navi.js

@@ -6273,12 +6273,16 @@ const route = (pattern, { searchParams } = {}) => {
       const routeUrl = resolveRouteUrl(routeRelativeUrl);
       return routeUrl;
     };
-    route.navTo = (params) => {
+    // Options travel as they do to navTo() itself — `routeTransition` is the
+    // one that matters here: what this one navigation asks of a route
+    // transition (see route_transition.jsx), which is the programmatic half of
+    // what a <Link routeTransition> says.
+    route.navTo = (params, options) => {
       if (!integration) {
         return Promise.resolve();
       }
       const routeUrl = route.buildUrl(params);
-      return integration.navTo(routeUrl);
+      return integration.navTo(routeUrl, options);
     };
     route.redirectTo = (params, { callReason } = {}) => {
       if (!integration) {
@@ -9250,8 +9254,7 @@ const createCalloutManager = (
       callout.update(message, calloutOptions);
       return;
     }
-    const resolvedAnchorElement =
-      anchorElement || controller.ref.current;
+    const resolvedAnchorElement = anchorElement || controller.ref.current;
     const removeCloseOnCleanup = addTeardown?.(() => {
       requestCloseCallout(new CustomEvent("cleanup"), "cleanup");
     });
@@ -14998,7 +15001,8 @@ const ONE_OF_CONSTRAINT = {
     );
     const isNoMatch = visibleOptions.length === 0;
     const message = field.controlHostProps["data-one-of-message"];
-    const noMatchMessage = field.controlHostProps["data-one-of-no-match-message"];
+    const noMatchMessage =
+      field.controlHostProps["data-one-of-no-match-message"];
     if (isNoMatch) {
       return noMatchMessage || naviI18n("constraint.one_of.no_match");
     }
@@ -15575,7 +15579,11 @@ const useDebugFocus = () => {
   const debug = useContext(DebugFocusContext);
   return debug || debugNoop;
 };
-/** Logger for virtual scroll / wheel motion (drag, momentum, glide), or a no-op. */
+/**
+ * Logger for virtual scroll / wheel motion (drag, momentum, glide) and for what
+ * a virtualized list does about it — the render window moving, and the rows the
+ * run asks for or decides not to ask for. Or a no-op.
+ */
 const useDebugScroll = () => {
   const debug = useContext(DebugScrollContext);
   return debug || debugNoop;
@@ -15618,7 +15626,9 @@ const useDebugUIState = () => {
  * @param {boolean|Function} [props.debugCommand] - navi command dispatch (`--navi-*`).
  * @param {boolean|Function} [props.debugInteraction] - Gated interactions; also implies focus/scroll/popup.
  * @param {boolean|Function} [props.debugFocus] - Focus moves and focus-visible decisions.
- * @param {boolean|Function} [props.debugScroll] - Virtual scroll / wheel motion.
+ * @param {boolean|Function} [props.debugScroll] - Virtual scroll / wheel motion,
+ *   the render window of a virtualized list, and every pass of its run — what it
+ *   asked for, or why it asked for nothing (see docs/list_refresh.md).
  * @param {boolean|Function} [props.debugPopup] - Popover/dialog open/close/positioning.
  * @param {boolean|Function} [props.debugAction] - Action lifecycle.
  * @param {boolean|Function} [props.debugUIState] - UI-state transitions and validation.
@@ -22120,8 +22130,67 @@ const setupBrowserIntegrationViaHistory = ({
     visitedUrlsSignal.value++;
   };
 
+  // The one thing the History API cannot say and the Navigation API can: what
+  // stands NEXT to the current entry. A link to the page one just came from is
+  // morally a back — pushed, it grows the stack (A, B, A, B…) and lands at the
+  // top; traversed, the stack stays what the reader thinks it is and the page
+  // comes back where they left it. So a push whose destination is the entry
+  // right behind (or right ahead) is turned into a traversal, and the whole
+  // traverse machinery (routing, scroll, movement) answers it as if the
+  // browser's own button had been pressed.
+  //
+  // Only where the browser exposes the stack (window.navigation — everywhere
+  // but Firefox today; without it a push stays a push, which is what this
+  // whole file already does). And only towards entries of THIS document: a
+  // traversal to another document is a full page load, which no press on a
+  // link asked for — the entries that are ours are recorded as they are
+  // created, starting with the one this document was loaded into.
+  const sameDocumentEntryKeys = new Set();
+  const rememberEntryIsOfThisDocument = () => {
+    if (window.navigation) {
+      sameDocumentEntryKeys.add(window.navigation.currentEntry.key);
+    }
+  };
+  rememberEntryIsOfThisDocument();
+  const adjacentEntryDelta = (url) => {
+    const { navigation } = window;
+    if (!navigation) {
+      return 0;
+    }
+    const entries = navigation.entries();
+    const index = navigation.currentEntry.index;
+    // Behind first: when the same page stands on both sides (A, B, A and one
+    // is on B), a link to it reads as going back.
+    for (const delta of [-1, 1]) {
+      const entry = entries[index + delta];
+      if (entry && entry.url === url && sameDocumentEntryKeys.has(entry.key)) {
+        return delta;
+      }
+    }
+    return 0;
+  };
+
   let abortController = null;
   const handleRoutingTask = (url, options) => {
+    // Decided before anything is announced: an elided push IS the traversal it
+    // becomes, and the traversal will make its own announcements when the
+    // browser answers — a before/after cycle here would be about a navigation
+    // that never happens.
+    if (
+      options.navigationType === "push" &&
+      options.state === undefined &&
+      url !== window.location.href
+    ) {
+      const delta = adjacentEntryDelta(url);
+      if (delta === -1) {
+        window.history.back();
+        return undefined;
+      }
+      if (delta === 1) {
+        window.history.forward();
+        return undefined;
+      }
+    }
     // Before anything is written: the visited set, the URL and every route are
     // about to change, and this is the last moment the page still stands as it
     // was. And after, whichever way the change went out — so that whoever took
@@ -22181,6 +22250,7 @@ const setupBrowserIntegrationViaHistory = ({
       } else {
         window.history.replaceState(effectiveState, null, url);
       }
+      rememberEntryIsOfThisDocument();
       updateDocumentUrl(url);
       updateDocumentState(effectiveState);
     } else {
@@ -22285,6 +22355,12 @@ const setupBrowserIntegrationViaHistory = ({
       handleRoutingTask(href, {
         reason: `"click" on a[href="${href}"]`,
         navigationType: "push",
+        // Who started it. Announced with the navigation because a press
+        // carries things the url does not: what a link asks of a route
+        // transition is the first of them (see route_transition.jsx). Read by
+        // whoever knows what to do with it, and it is the anchor itself —
+        // resolved here, where it already is.
+        element: linkElement,
       });
     },
     { capture: true },
@@ -22322,11 +22398,15 @@ const setupBrowserIntegrationViaHistory = ({
     updateDocumentUrl(window.location.href);
   });
 
-  const navTo = async (url, { replace, state } = {}) => {
+  const navTo = async (url, { replace, state, routeTransition } = {}) => {
     handleRoutingTask(url, {
       reason: `navTo called with "${url}"`,
       navigationType: replace ? "replace" : "push",
       state,
+      // What this one navigation asks of a route transition, said by the call
+      // that starts it rather than by an element — the programmatic half of
+      // what a <Link routeTransition> says (see route_transition.jsx).
+      routeTransition,
     });
   };
 
@@ -22478,7 +22558,9 @@ const applyRouting = (
   return { ...updateActionsResult, activeRouteSet };
 };
 
-const browserIntegration = setupBrowserIntegrationViaHistory({
+const setupBrowserIntegration =
+  setupBrowserIntegrationViaHistory;
+const browserIntegration = setupBrowserIntegration({
   applyActions,
   applyRouting,
   // Routes are declared by the consumer and registered through
@@ -38666,6 +38748,18 @@ installImportMetaCssBuild(import.meta);/**
  * own CSS (see the JSDoc below). Said without one, the relation plays the
  * browser's cross-fade.
  *
+ * A relation holds for every way of reaching a page, and one navigation may
+ * know better: the rare way round a pair — a badge that jumps back OUT to the
+ * game it belongs to, a card that leads to the player it describes — is walked
+ * against the map, and there is no telling it from the common way by the
+ * routes alone. So the navigation itself may ask for something: a `<Link
+ * routeTransition>`, or navTo(url, { routeTransition }). What it asks holds
+ * for THAT
+ * navigation and no other, and only for the fields it names — `{ direction:
+ * "back" }` keeps the pair's movement and turns it round (see
+ * readNavigationRequest). A pair no relation was ever written for animates the
+ * same way, for the one press that asks.
+ *
  * There is no box in the tree: by default what animates is the document itself
  * (its `root` view transition group), which is right for pages that ARE the
  * whole viewport. An application whose pages live between fixed bars marks the
@@ -38699,6 +38793,10 @@ const TRANSITION_DURATION_PROPERTY = "--navi-route-transition-duration";
 // right for a page that IS the whole viewport.
 const TRANSITION_AREA_ATTRIBUTE = "data-navi-route-transition-area";
 const TRANSITION_TARGET_ATTRIBUTE = "data-navi-route-transition-target";
+// What ONE navigation asks for, over whatever the relations say: worn by the
+// link being pressed (see <Link routeTransition>), or handed to navTo(). It answers
+// for that navigation and for no other — the next one is back to the relations.
+const TRANSITION_REQUEST_ATTRIBUTE = "data-navi-route-transition-request";
 const AREA_NAME = "navi-route-transition";
 // route_travel.jsx wears this on the root for the length of one of its
 // travels (its TRAVEL_ATTRIBUTE — a comment there mirrors this one). Read by
@@ -38844,10 +38942,13 @@ const css$T = /* css */`
        The movements. One of \`root\` and \`navi-route-transition\` exists at a
        time (see the opt-out above), so each is written for both.
        ------------------------------------------------------------------ */
-    &[data-navi-route-transition-type="slide-x"],
-    &[data-navi-route-transition-type="slide-y"],
-    &[data-navi-route-transition-type="cover-x"],
-    &[data-navi-route-transition-type="cover-y"] {
+    /* What a NAMED movement is made of, whatever the movement is — the types
+       navi ships and the ones an application writes alike. The attribute is
+       present for a type and only for a type ("cross-fade" normalizes to no
+       type at all, "none" starts nothing), so the browser's own cross-fade
+       keeps every default below: scaling one picture into the other and seeing
+       through both IS the movement there. */
+    &[data-navi-route-transition-type] {
       &::view-transition-old(root),
       &::view-transition-new(root),
       &::view-transition-old(navi-route-transition),
@@ -38857,20 +38958,34 @@ const css$T = /* css */`
            the page it crosses. The picture is as wide as the box the browser
            gives it — the arriving one's — so a page leaving a narrower box (a
            scrollbar appeared, a side panel closed) would be seen zooming over
-           the length of the movement. Left to the untyped cross-fade, where
-           scaling one picture into the other is the whole idea. */
+           the length of the movement, and one leaving a shorter box would be
+           seen inflating. */
         height: auto;
         object-fit: none;
         object-position: top left;
-        /* The default cross-fade, dropped: two pages sliding past each other
-           are two solid things, and seeing through one to the other says they
-           are the same page changing its mind. */
+        /* Two pages crossing are two solid things, and seeing through one to
+           the other says they are the same page changing its mind. A movement
+           that keeps the browser's fade on one of its two sides wants the
+           opposite, and says so — see zoom below. */
         mix-blend-mode: normal;
-        animation-timing-function: ease;
         animation-fill-mode: both;
       }
     }
 
+    /* Eased, which is a taste about THESE four: a custom type says its own
+       curve. */
+    &[data-navi-route-transition-type="slide-x"],
+    &[data-navi-route-transition-type="slide-y"],
+    &[data-navi-route-transition-type="cover-x"],
+    &[data-navi-route-transition-type="cover-y"] {
+      &::view-transition-old(root),
+      &::view-transition-new(root),
+      &::view-transition-old(navi-route-transition),
+      &::view-transition-new(navi-route-transition) {
+        animation-timing-function: ease;
+      }
+    }
+
     &[data-navi-route-transition-type="slide-x"] {
       &[data-navi-route-transition="forward"] {
         &::view-transition-old(root),
@@ -38983,7 +39098,11 @@ const css$T = /* css */`
       &::view-transition-new(root),
       &::view-transition-old(navi-route-transition),
       &::view-transition-new(navi-route-transition) {
-        animation-fill-mode: both;
+        /* One side of this one is the browser's fade, and a fade is two
+           half-transparent pictures: they must ADD up rather than cover each
+           other, or the page behind shows through the middle of the
+           movement. */
+        mix-blend-mode: plus-lighter;
       }
       &[data-navi-route-transition="forward"] {
         &::view-transition-new(root),
@@ -39136,6 +39255,12 @@ const RouteTransitionArea = ({
  *         animation-name: my-spin-in;
  *       }
  *     }
+ *
+ *   Whatever is written here is what EVERY crossing of the pair plays. One
+ *   crossing can ask for something else — `<Link routeTransition>`, or
+ *   navTo(url, { routeTransition }) — which overrides this field by field, for
+ *   that
+ *   navigation alone.
  * @returns {() => void} remove this relation.
  */
 const defineRouteTransition = (from, to, transition) => {
@@ -39152,13 +39277,11 @@ const defineRouteTransition = (from, to, transition) => {
   };
   relations.push(relation);
   rebuildWatcher();
-  updateRoutingObservers();
   return () => {
     const index = relations.indexOf(relation);
     if (index > -1) {
       relations.splice(index, 1);
       rebuildWatcher();
-      updateRoutingObservers();
     }
   };
 };
@@ -39180,11 +39303,9 @@ const defineRouteDefaultTransition = transition => {
   import.meta.css = [css$T, "@jsenv/navi/src/nav/route_transition.jsx"];
   const value = normalizeTransition(transition);
   defaultTransition = value;
-  updateRoutingObservers();
   return () => {
     if (defaultTransition === value) {
       defaultTransition = null;
-      updateRoutingObservers();
     }
   };
 };
@@ -39205,6 +39326,98 @@ const normalizeTransition = transition => {
   };
 };
 
+/**
+ * What THIS navigation asked for, whatever the relations say.
+ *
+ * A relation is about the map of the app and holds for every way of reaching a
+ * page; a request is about one crossing of it. The rare way round a pair — a
+ * badge that jumps back out to the game it belongs to, a card that leads to
+ * the player it describes — is a navigation that knows something the pair does
+ * not, and this is where it says it.
+ *
+ * Two mouths, one meaning: the element being pressed wears it (a `<Link
+ * routeTransition>`, or the attribute by hand on any anchor), or navTo() is
+ * handed
+ * it. Both arrive here through the announcement the navigation makes before it
+ * writes anything (see before_routing.js).
+ *
+ * A request answers FIELD BY FIELD: what it does not say, the relation — or
+ * the default — still answers for. So `{ direction: "back" }` keeps the pair's
+ * movement and only turns it round, and `"none"` cuts where something would
+ * have played.
+ */
+const readNavigationRequest = ({
+  routeTransition,
+  element
+}) => {
+  if (routeTransition !== undefined && routeTransition !== null) {
+    return normalizeRequest(routeTransition);
+  }
+  if (element && element.getAttribute) {
+    const asked = element.getAttribute(TRANSITION_REQUEST_ATTRIBUTE);
+    if (asked === null) {
+      return null;
+    }
+    const value = asked.trim();
+    if (value === "") {
+      return null;
+    }
+    // A type is a name, and a name is all most links have to say. Anything
+    // more — a way round, a pace — is the same object the API takes
+    // everywhere else, written as JSON so that it travels on an attribute
+    // (and so that a plain <a> can say it too).
+    if (value[0] === "{") {
+      let parsed;
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        console.warn(`${TRANSITION_REQUEST_ATTRIBUTE} is neither a type name nor JSON: ${value}`);
+        return null;
+      }
+      return normalizeRequest(parsed);
+    }
+    return normalizeRequest(value);
+  }
+  return null;
+};
+const normalizeRequest = transition => {
+  const {
+    type,
+    duration,
+    direction
+  } = typeof transition === "string" ? {
+    type: transition
+  } : transition;
+  return {
+    type: type === "cross-fade" ? undefined : type,
+    // Whether a type was SAID, which is not the same as having one: asking for
+    // "cross-fade" is asking for the browser's own animation, and a request
+    // that names no type at all keeps the relation's.
+    typeSaid: type !== undefined,
+    duration,
+    direction
+  };
+};
+
+// The request first, field by field, then what was defined for this pair (or
+// for everything). Written as one function because both ends of the file
+// resolve the same way: the one that knows the pair, and the one that only
+// knows a navigation landed.
+const resolveTransition = (request, base) => {
+  const baseType = base ? base.type : undefined;
+  const baseDuration = base ? base.duration : undefined;
+  if (!request) {
+    return {
+      type: baseType,
+      duration: baseDuration
+    };
+  }
+  return {
+    type: request.typeSaid ? request.type : baseType,
+    duration: request.duration === undefined ? baseDuration : request.duration
+  };
+};
+
 // Every relation defined, and the single watcher standing over all of them.
 const relations = [];
 let watcher = null;
@@ -39248,27 +39461,32 @@ const rebuildWatcher = () => {
       return;
     }
     const found = findRelation(pages[fromIndex], pages[index]);
-    if (!found) {
-      // No relation says anything about these two: they are side by side, and
-      // silence is the fact — not a missing case.
+    if (!found && !navigationRequest) {
+      // No relation says anything about these two and this navigation asked
+      // for nothing: they are side by side, and silence is the fact — not a
+      // missing case.
       return;
     }
     const {
-      direction,
-      relation
-    } = found;
-    if (relation.type === "none") {
+      type,
+      duration
+    } = resolveTransition(navigationRequest, found ? found.relation : null);
+    if (type === "none") {
       // Silence said out loud: this way of the pair was written to play
-      // nothing, where the reverse of the other way — or the default — would
-      // have played.
+      // nothing — or this one navigation asked for nothing — where the reverse
+      // of the other way, or the default, would have played.
       navigationAnimated = true;
       return;
     }
     beginTransition({
       page: pages[index],
-      direction,
-      type: relation.type,
-      duration: relation.duration
+      // Which way it plays: what the navigation itself said first — the link
+      // being pressed is where the way the app is being walked is known — then
+      // the relation, and forward for a navigation that asked for a movement
+      // between two pages no relation orders.
+      direction: navigationRequest && navigationRequest.direction || found && found.direction || "forward",
+      type,
+      duration
     });
   };
   // `subscribe` rather than `effect`: it hands the value to a callback that is
@@ -39280,52 +39498,57 @@ const rebuildWatcher = () => {
   };
 };
 
-// What plays when no relation matched (see defineRouteDefaultTransition), and
-// whether the navigation now landing found an answer already — a relation's
-// transition, a "none", a RouteTravel travel. The flag is reset when a
-// navigation begins, so it is always about the latest one.
+// What plays when no relation matched (see defineRouteDefaultTransition), what
+// the navigation now landing asked for on its own (see readNavigationRequest),
+// and whether it found an answer already — a relation's transition, a "none",
+// a RouteTravel travel. The last two are read at the start of every
+// navigation, so they are always about the latest one.
 let defaultTransition = null;
+let navigationRequest = null;
 let navigationAnimated = false;
 
-// The two ends of a navigation, watched while there is anyone to animate it.
-// The picture of the page being left has to be honest, so rendering is held
-// from before the navigation's first write (see rendering_hold.js) — and given
-// back at the far end when the change turns out to be one nobody animates,
-// which is also the one moment the DEFAULT can decide: every relation has had
-// its say by then.
-let stopRoutingObservers = null;
-const updateRoutingObservers = () => {
-  const wanted = relations.length > 0 || defaultTransition !== null;
-  if (wanted && !stopRoutingObservers) {
-    const stopWatchingStart = observeBeforeRouting(() => {
-      navigationAnimated = false;
-      holdRenderingForRouting();
-    });
-    const stopWatchingEnd = observeAfterRouting(() => {
-      if (defaultTransition && defaultTransition.type !== "none" && !navigationAnimated) {
-        beginTransition({
-          page: null,
-          // A default has no direction: nothing says which of two arbitrary
-          // pages is before the other. The attribute is worn empty — present
-          // for whoever keys on "one of ours is playing", silent on the way.
-          direction: "",
-          type: defaultTransition.type,
-          duration: defaultTransition.duration
-        });
-      }
-      releaseRoutingRenderingHold();
-    });
-    stopRoutingObservers = () => {
-      stopWatchingStart();
-      stopWatchingEnd();
-    };
+// The two ends of every navigation, watched from here on. The picture of the
+// page being left has to be honest, so rendering is held from before the
+// navigation's first write (see rendering_hold.js) — but only when something
+// could be photographed: a document where nothing is defined and nothing is
+// asked for holds nothing. It is given back at the far end, which is also the
+// one moment the DEFAULT can decide: every relation has had its say by then.
+observeBeforeRouting(details => {
+  navigationAnimated = false;
+  navigationRequest = readNavigationRequest(details);
+  if (relations.length === 0 && !defaultTransition && !navigationRequest) {
     return;
   }
-  if (!wanted && stopRoutingObservers) {
-    stopRoutingObservers();
-    stopRoutingObservers = null;
+  holdRenderingForRouting();
+});
+observeAfterRouting(() => {
+  const request = navigationRequest;
+  // Read here and dropped here: a request answers for the navigation it was
+  // made on, and the next one is back to the relations.
+  navigationRequest = null;
+  if (!navigationAnimated && (request || defaultTransition)) {
+    const {
+      type,
+      duration
+    } = resolveTransition(request, defaultTransition);
+    if (type !== "none") {
+      beginTransition({
+        page: null,
+        // A default has no direction: nothing says which of two arbitrary
+        // pages is before the other, and the attribute is then worn empty —
+        // present for whoever keys on "one of ours is playing", silent on the
+        // way. A request is the other case: a navigation IS a way round, so a
+        // press that names the movement means forward unless it says
+        // otherwise — and a movement of navi's is written on the direction,
+        // so left empty it would play nothing at all.
+        direction: request && request.direction || (request && request.typeSaid ? "forward" : ""),
+        type,
+        duration
+      });
+    }
   }
-};
+  releaseRoutingRenderingHold();
+});
 
 // The exact way travelled first, over the whole registry, and only then the
 // reverses: a relation written B → A owns that way, and being the reverse of
@@ -43501,6 +43724,14 @@ Object.assign(PSEUDO_CLASSES, {
  *   out of flow — the "#" anchor-on-hover pattern (e.g. inside a `Title`).
  * @param {boolean} [props.hrefFallback] - Use `href` as the visible text when
  *   no children are given; defaults to `true` unless `anchor`.
+ * @param {string|{type?: string, duration?: number|string, direction?: "forward"|"back"}} [props.routeTransition] -
+ *   What pressing THIS link asks of a route transition, for that one
+ *   navigation: a type name (`"slide-x"`, `"none"`, …), or an object to also
+ *   say the pace or which way it plays. It overrides field by field what
+ *   `defineRouteTransition` wrote for the pair — `{ direction: "back" }` keeps
+ *   the pair's movement and only turns it round, which is what the rare way
+ *   round a pair usually needs. Said nowhere else, the relations answer as
+ *   they always do.
  * @param {boolean} [props.preventDefault] - Call `event.preventDefault()` on
  *   click (navigation suppressed; `onClick` still runs).
  * @param {(event: MouseEvent) => void} [props.onClick]
@@ -43564,6 +43795,7 @@ const LinkPlain = props => {
     endIcon,
     revealOnInteraction = false,
     hrefFallback = !anchor,
+    routeTransition,
     children
   } = props;
   if (anchor && !props.id) {
@@ -43670,6 +43902,13 @@ const LinkPlain = props => {
   } else {
     innerEndIcon = endIcon;
   }
+
+  // What this link asks of a route transition, worn as an attribute so that
+  // the navigation reads it off the element being pressed (see
+  // route_transition.jsx, which owns the name and does the reading). A type is
+  // a name; anything more travels as JSON, which is also how a plain <a>
+  // writes it by hand.
+  const routeTransitionRequest = routeTransition === undefined || routeTransition === null ? undefined : typeof routeTransition === "string" ? routeTransition : JSON.stringify(routeTransition);
   const innerChildren = children || (hrefFallback ? href : children);
   const startIconEl = startIcon;
   const endIconEl = innerEndIcon;
@@ -43720,6 +43959,8 @@ const LinkPlain = props => {
     startIcon: undefined,
     endIcon: undefined,
     hrefFallback: undefined,
+    routeTransition: undefined,
+    "data-navi-route-transition-request": routeTransitionRequest,
     onClick: e => {
       onClick?.(e);
       if (slide) {
@@ -60331,6 +60572,18 @@ const useItemStore = ({
   memoryBudget,
   onRequestStateChange
 }) => {
+  // The run's asking, on the same channel as the window it asks for — they are
+  // one subject: what the list is about to draw is what it goes to fetch (see
+  // `useRequestMissing`, and `updateRenderWindow` which logs the other half).
+  //
+  // A run that decides NOT to ask is the case this exists for. It sends
+  // nothing and changes no state, so nothing outside can see it: the network
+  // is silent, and `onRequestStateChange` — which reports what a request is
+  // doing — has no request to report. A run that declined and a run that was
+  // never mounted look identical from the application's side, which makes
+  // "this list stopped refreshing" a question with no observable answer.
+  // Here it has one, and every pass says which.
+  const debugScroll = useDebugScroll();
   // What the source kept of the collection when the screen it was on went away
   // (a range reader keeps the composition: see resource_range_reader.js). The
   // rows are drawn from it right away and the window is asked for again — the
@@ -60557,17 +60810,32 @@ const useItemStore = ({
         }
       }
       const ask = () => {
+        // One line per pass, whatever the outcome — an absence in the trace
+        // then means the run did not render, which is a different fact from
+        // the run choosing not to ask. The state that decides is on the line
+        // rather than left to be inferred: `revalidating` says the run knows
+        // what it holds is from before, `holdPending` that the list is on its
+        // way somewhere the window does not frame yet, `count` that it knows
+        // how many rows it stands for.
+        const debugAsk = outcome => {
+          debugScroll(`ask ${start}-${end}: ${outcome}`, `(revalidating=${revalidating} holdPending=${virtual.holdPending} count=${pages.count})`);
+        };
         if (start === -1) {
+          // Nothing missing and nothing to revalidate: the run has what it
+          // draws.
+          debugAsk("nothing missing");
           return;
         }
         if (virtual.holdPending && pages.count !== undefined && !askingAroundWantedRow) {
           // The one ask a hold lets through: the row the list is held on is
           // what would lift the hold, and nothing else is going to bring it.
+          debugAsk("held on a row not reached yet");
           return;
         }
         const request = requestRef.current;
         if (revalidating && request.busy) {
           if (request.revalidating) {
+            debugAsk("already revalidating");
             return;
           }
           // A page for a window that is about to be replaced wholesale.
@@ -60585,6 +60853,7 @@ const useItemStore = ({
           // waiting for to exist at all.
           const stillWanted = pages.count === undefined || request.start <= windowTo && request.end >= windowFrom;
           if (stillWanted) {
+            debugAsk("a request still covers this window");
             return;
           }
           request.controller?.abort();
@@ -60595,6 +60864,7 @@ const useItemStore = ({
         // nothing since, can only produce the same answer. A revalidation is
         // exactly the case where it produces another one.
         if (!revalidating && request.start === start && request.end === end && request.held === held) {
+          debugAsk("this range was asked for already");
           return;
         }
         request.start = start;
@@ -60618,6 +60888,7 @@ const useItemStore = ({
         };
         request.busy = true;
         request.revalidating = revalidating;
+        debugAsk("sent");
         if (revalidating) {
           setRefreshing(true);
         }