@jsenv/navi 0.29.417 → 0.29.419

package/dist/dev/jsenv_navi.js

@@ -11254,6 +11254,28 @@ const suspendScrollRecording = () => {
   };
 };
 
+// A list scrolling the document that opens on a row puts the document where
+// that row is, by measuring it (see placeWhereHeld in list.jsx). The offset kept
+// for the url is pixels of the page as it was drawn — and a list draws a window
+// of its rows and holds the room of the others with fillers of an estimated
+// height, so the same pixels now fall on other rows. Put back after the list
+// has placed itself, they would undo it, in the very picture a route transition
+// takes. So the list holds the document while it is placing itself, and the
+// url's offset is not put back meanwhile. Counted: two lists can share one
+// document.
+let documentHoldCount = 0;
+const holdDocumentScroll = () => {
+  documentHoldCount++;
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    documentHoldCount--;
+  };
+};
+
 let installed = false;
 const installScrollRestoration = () => {
   if (installed) {
@@ -11288,6 +11310,9 @@ const installScrollRestoration = () => {
   if (positionOnLoad && (positionOnLoad.x || positionOnLoad.y)) {
     const stopListening = observeRouteRender(() => {
       stopListening();
+      if (documentHoldCount) {
+        return;
+      }
       scrollTo(positionOnLoad);
     });
   }
@@ -11302,6 +11327,11 @@ const restoreScrollPosition = (url) => {
   if (!position) {
     return false;
   }
+  if (documentHoldCount) {
+    // There is a place to go back to, and the list holding the document is
+    // putting it back (see holdDocumentScroll).
+    return true;
+  }
   scrollTo(position);
   return true;
 };
@@ -15033,7 +15063,11 @@ const createOpenController = (
     const applyChange = () => {
       // Recorded with the change itself: what the DOM shows is what a render
       // landing between the ask and the picture must draw (see `openedInDom`).
-      controller.openedInDom = opened;
+      // An opening records it inside the change, once its content is built
+      // (see open() below).
+      if (!opened) {
+        controller.openedInDom = false;
+      }
       change();
     };
     const { transitionChange } = controller;
@@ -15313,15 +15347,17 @@ const createOpenController = (
           controller.mountContent?.();
           // Only now — after the content has been built, before openEffect
           // shows it. Dialog/Popover recompute aria-expanded and navi-hidden
-          // from this flag on every render, and mountContent above renders
+          // from `openedInDom` on every render, and mountContent above renders
           // synchronously: flipping it any earlier commits an already-open DOM
           // (aria-expanded "true", navi-hidden gone) before openEffect has run
           // a single statement, so the "closed" frame it pins to transition
           // from is in fact the open one and the entrance animation has
-          // nothing to play. It also gives the content it just built the
-          // opening it is documented to observe — mounted while the popup
-          // reads as closed, told it opened right after (see
-          // popup_content_mount.js and use_displayed_layout_effect.js).
+          // nothing to play — on every first opening that builds its content.
+          // It also gives the content it just built the opening it is
+          // documented to observe — mounted while the popup reads as closed,
+          // told it opened right after (see popup_content_mount.js and
+          // use_displayed_layout_effect.js).
+          controller.openedInDom = true;
           controller.opened = true;
           // Which press it opened during, so the release of that press is not
           // read as somebody dismissing it (see openedDuringThisPress).
@@ -15730,7 +15766,14 @@ const useOpenPropsEffectOnOpenController = (
     lastRunOpenRef.current = open;
 
     if (isFirstRun) {
-      const mountOpenReason = open || defaultOpen;
+      // "interaction" is said even over what the caller holds reading open: a
+      // popup built by the request that opens it — a dialog standing in until
+      // its signal said open, see DialogStandIn in dialog.jsx — mounts BECAUSE
+      // of that opening.
+      const mountOpenReason =
+        open && defaultOpen === "interaction"
+          ? "interaction"
+          : open || defaultOpen;
       if (mountOpenReason) {
         // Whether this popup being open is something that just happened, or
         // something that was already true when the page appeared. "interaction"
@@ -28663,6 +28706,18 @@ const useAsyncData = (promiseOrAction, {
 
 // ─── useAction ────────────────────────────────────────────────────────────────
 
+// subscribe() calls back at once with the value the signal holds; what these
+// subscriptions are for is what changes after.
+const subscribeToChanges = (signal, onChange) => {
+  let initial = true;
+  return signal.subscribe(value => {
+    if (initial) {
+      initial = false;
+      return;
+    }
+    onChange(value);
+  });
+};
 const LoadingContext = createContext(null);
 const actionPendingPromiseWeakMap = new WeakMap();
 const dismissedActionWeakSet = new WeakSet();
@@ -28707,6 +28762,15 @@ const useActionAsyncData = (action, {
   const runningState = action.runningStateSignal.peek();
   const [, setTick] = useState(0);
   const routePage = useContext(RoutePageContext);
+  // What this render read of the action, for the subscriptions below to tell
+  // a change that came between the render and them from none at all.
+  const readRef = useRef(null);
+  readRef.current = {
+    runningState,
+    data: action.dataSignal.peek(),
+    params: action.paramsSignal.peek(),
+    settling: action.paramsSettlingSignal.peek()
+  };
   useEffect(() => {
     let stopOwingRender = null;
     const rerender = () => {
@@ -28734,7 +28798,12 @@ const useActionAsyncData = (action, {
       }
       setTick(n => n + 1);
     };
-    const unsubscribeFromRunningState = action.runningStateSignal.subscribe(state => {
+    // A run under way is a new try: an error dismissed before it is not the
+    // one it may end on.
+    if (action.runningStateSignal.peek() === RUNNING) {
+      dismissedActionWeakSet.delete(action);
+    }
+    const unsubscribeFromRunningState = subscribeToChanges(action.runningStateSignal, state => {
       if (state === RUNNING) {
         dismissedActionWeakSet.delete(action);
       }
@@ -28745,38 +28814,24 @@ const useActionAsyncData = (action, {
     // (a PUT upserting an item that a GET_MANY list already holds) changes the
     // data while this action stays COMPLETED. Subscribing here re-renders
     // through the same controlled path as the run state, instead of `.value`.
-    let dataNotificationIsInitial = true;
-    const unsubscribeFromData = action.dataSignal.subscribe(() => {
-      if (dataNotificationIsInitial) {
-        // subscribe() calls back synchronously with the current value
-        dataNotificationIsInitial = false;
-        return;
-      }
-      rerender();
-    });
+    const unsubscribeFromData = subscribeToChanges(action.dataSignal, rerender);
     // The params say WHICH question this is, and this hook reads them: to know
     // there is nothing to ask for, and to start the run it owns. A binding
     // retargeting from no question to a question — a filter chosen, a first
     // character typed — is announced by nothing above: a fresh target is IDLE
     // holding no data, the very state the hook already sees.
-    let paramsNotificationIsInitial = true;
-    const unsubscribeFromParams = action.paramsSignal.subscribe(() => {
-      if (paramsNotificationIsInitial) {
-        paramsNotificationIsInitial = false;
-        return;
-      }
-      rerender();
-    });
+    const unsubscribeFromParams = subscribeToChanges(action.paramsSignal, rerender);
     // A debounced binding waits before it retargets, so nothing above changes
     // while the delay runs — but what is on screen is already out of date.
-    let settlingNotificationIsInitial = true;
-    const unsubscribeFromParamsSettling = action.paramsSettlingSignal.subscribe(() => {
-      if (settlingNotificationIsInitial) {
-        settlingNotificationIsInitial = false;
-        return;
-      }
+    const unsubscribeFromParamsSettling = subscribeToChanges(action.paramsSettlingSignal, rerender);
+    // Subscribed once the browser has painted, so the action may have moved
+    // since the render: a run that very render started may be over already,
+    // and nothing would say so again. What the render read, against what is
+    // there now — and nothing moved, nothing to draw again.
+    const read = readRef.current;
+    if (action.runningStateSignal.peek() !== read.runningState || action.dataSignal.peek() !== read.data || action.paramsSignal.peek() !== read.params || action.paramsSettlingSignal.peek() !== read.settling) {
       rerender();
-    });
+    }
     return () => {
       unsubscribeFromRunningState();
       unsubscribeFromData();
@@ -40354,6 +40409,17 @@ const useDisplayedLayoutEffect = (ref, callback, deps) => {
         decisionDeferredToRef.current = popupMounting;
         return;
       }
+      if (
+        (el.tagName === "DIALOG" || el.hasAttribute("popover")) &&
+        !isAncestorOpen(el)
+      ) {
+        // Itself a closed <dialog> or [popover]: display:none by the UA's own
+        // rules, which the markup says without asking the layout — asked, every
+        // closed popup mounting would force a style recalculation, and a list
+        // whose rows each hold a few mounts hundreds of them. The observer
+        // below fires as for any element the ancestor hides.
+        return;
+      }
       if (!isDisplayedDespiteClosedAncestor(el, ancestor)) {
         // Ancestor is closed and took this element off screen with it — skip
         // now; the observeAncestorOpenState call below will fire once it
@@ -52612,9 +52678,9 @@ const FixedBar = ({
  * A page that overflows horizontally is a bug wherever it happens, and on
  * Chrome Android it is a catastrophic one: the layout viewport inflates to the
  * content and `position: fixed` centering goes with it (see
- * docs/mobile_layout_pitfalls.md). The remedy there is a wrapper in
- * `overflow-x: clip`, and it works — at the price of making the cause
- * invisible: nothing sticks out anymore, so nothing says a fixed width, a
+ * docs/safe_area.md#a-document-wider-than-the-screen). The remedy there is a
+ * wrapper in `overflow-x: clip`, and it works — at the price of making the
+ * cause invisible: nothing sticks out anymore, so nothing says a fixed width, a
  * `min-width` or an unbreakable string is still oversized. This puts the
  * signal back, without giving up the net.
  *
@@ -65627,7 +65693,9 @@ const css$E = /* css */`
  * @param {"always"|"idle"|"from-first-open"|"while-opened"} [props.mount] - When
  *   `children` are built and thrown away (see popup_content_mount.js).
  *   `"from-first-open"` (the default) builds them on the first open and keeps
- *   them afterwards. `"always"` builds them right away, for content something
+ *   them afterwards — and the dialog itself is built then too: until its first
+ *   request (an open, a press on what opens it, its signal saying open) it is
+ *   a bare `<dialog>` holding its id (see docs/popup_open.md). `"always"` builds them right away, for content something
  *   depends on while the popup is still closed: a value read off it, fields a
  *   surrounding form collects on submit, a size measured from outside.
  *   `"idle"` builds them in a browser idle moment after load — "always" minus
@@ -65648,11 +65716,122 @@ const Dialog = props => {
       ...props
     });
   }
-  return jsx(UncontrolledDialog, {
+  return jsx(DialogStandIn, {
     ...props
   });
 };
 
+// A dialog nobody has asked for yet stands in as its bare <dialog>. That
+// element is all that reaches a closed dialog before its first opening: a
+// command finds it by id (`commandfor`) and asks it to open, a press on what
+// opens it announces itself on it (navi_open_press), --navi-toggle reads its
+// aria-expanded. The dialog proper — its open controller, its box, its focus
+// and pseudo-class wiring — is built at the first request: an open, a press
+// about to open it, its signal or its `open` saying open. A list whose rows
+// each hold a few dialogs mounts hundreds of them, and would pay for every one
+// at every mount, for openings that mostly never come. Built once, the dialog
+// stays: the next opening finds it there.
+const DialogStandIn = props => {
+  const {
+    ref,
+    id,
+    signal,
+    value,
+    open
+  } = props;
+  const ownRef = useRef();
+  const dialogRef = ref || ownRef;
+  // Why the dialog proper exists, once it does; never undone.
+  const builtRef = useRef(null);
+  const mountedRef = useRef(false);
+  const isMount = !mountedRef.current;
+  mountedRef.current = true;
+  // Its own reading of the signal: the dialog of one card among many, told
+  // apart by `value`, follows whether IT is the one open rather than every
+  // write the others cause.
+  const openedSignal = useMemo(() => signal ? computed(() => readOpened(signal.value, value)) : null, [signal, value]);
+  const openedBySignal = openedSignal ? openedSignal.value : false;
+  if (builtRef.current === null) {
+    if (isMount && (needsDialogFromMount(props) || open || openedBySignal)) {
+      builtRef.current = "mount";
+    } else if (open || openedBySignal) {
+      // Asked open while this stood in: the opening is happening now, and it
+      // plays like any other (see defaultOpen "interaction").
+      builtRef.current = "interaction";
+    }
+  }
+  const [, setBuildCount] = useState(0);
+  const warmRef = useRef(null);
+  const build = reason => {
+    if (builtRef.current !== null) {
+      return;
+    }
+    builtRef.current = reason;
+    flushSyncRendering(() => {
+      setBuildCount(count => count + 1);
+    });
+  };
+  const builtReason = builtRef.current;
+  if (builtReason !== null) {
+    return jsx(UncontrolledDialog, {
+      ...props,
+      ref: dialogRef,
+      defaultOpen: builtReason === "interaction" ? "interaction" : props.defaultOpen
+    });
+  }
+  return jsx("dialog", {
+    ref: dialogRef,
+    id: id,
+    className: "navi_dialog"
+    // eslint-disable-next-line react/no-unknown-property
+    ,
+    "navi-hidden": ""
+    // eslint-disable-next-line react/no-unknown-property
+    ,
+    "navi-out-of-flow": "",
+    "aria-expanded": "false",
+    "data-testid": props["data-testid"]
+    // eslint-disable-next-line react/no-unknown-property
+    ,
+    onnavi_request_open: e => {
+      // Built in this same event, and asked again: the opening is the one
+      // the dialog proper would have had — its source, its anchor, its value.
+      build("request");
+      const opened = dispatchCustomEvent(dialogRef.current, "navi_request_open", e.detail);
+      if (!opened) {
+        e.preventDefault();
+      }
+    }
+    // eslint-disable-next-line react/no-unknown-property
+    ,
+    onnavi_open_press: () => {
+      // What the opening will read is asked for at once, as the dialog
+      // proper does (see open_controller.js); the dialog itself two frames
+      // later, so the pressed trigger is painted first — the click that
+      // follows opens it built, or builds it itself when it comes sooner.
+      if (signal) {
+        preloadState(signal, readOpenValue(value));
+      }
+      if (warmRef.current) {
+        return;
+      }
+      warmRef.current = requestFrameAfterNext(() => {
+        warmRef.current = null;
+        build("press");
+      });
+    }
+  });
+};
+// What needs the dialog proper from the start: an opening at mount, content
+// built ahead of any opening, a history entry to read, an anchor whose hover
+// or focus builds the content ahead of the click.
+const needsDialogFromMount = props => {
+  if (props.defaultOpen || props.navState || props.anchor !== undefined) {
+    return true;
+  }
+  return props.mount !== undefined && props.mount !== "from-first-open";
+};
+
 // No openController passed: this Dialog is used declaratively (e.g. driven
 // by --navi-toggle/--navi-open/--navi-close commands, the `open` prop, or
 // `defaultOpen`) rather than owned by a parent component.
@@ -72626,9 +72805,17 @@ const ListUI = props => {
   // why not an effect), and the floor of 30 is its: it protects the scrolling
   // window, not a picture nobody has seen yet.
   const {
-    initial: initialRenderBudget,
+    initial: initialRenderBudgetProp,
     after: renderBudgetAfterPaint
   } = resolveRenderBudget(renderBudgetProp);
+  // Opening on a position that says how many rows were on screen from its row
+  // on (the way back to where the list was, see reportPosition): that is what
+  // the first picture shows, whatever `initial` guessed — with the row above
+  // when it stood partly in view. The rest waits for the paint like any
+  // `initial`: a page coming back in a route transition builds it inside the
+  // update callback, and every row below the fold delays the movement.
+  const openingPosition = scrolled ?? defaultScrolled;
+  const initialRenderBudget = openingPosition && typeof openingPosition === "object" && typeof openingPosition.visibleCount === "number" ? openingPosition.visibleCount + (openingPosition.offset > 0 ? 1 : 0) : initialRenderBudgetProp;
   let renderBudget = renderBudgetAfterPaint;
   if (renderBudget < 30 && !renderBudgetSkipCheck) {
     console.warn(`List: renderBudget=${renderBudget} is too low. A renderBudget below 30 is not supported: on large screens or when the list grows, items outside the window would appear as blank space instead of rendered content. Use a value of at least 30, or omit the prop to use the default (${RENDER_BUDGET_DEFAULT}).`);
@@ -73091,11 +73278,23 @@ const useListScrollSync = ({
       horizontal
     });
   };
+
+  // How many rows the window keeps above the row the list is held at. Around it
+  // for the scrolling to come, from the first paint on; before, the window is
+  // the first picture's, and a picture of the list opening on a row shows that
+  // row and what is below it — with the one above when a remembered position
+  // says it stood partly in view.
+  const rowsAboveOpening = (openAt, windowSize) => {
+    if (renderBudget !== renderBudgetSteady) {
+      return openAt && typeof openAt === "object" && openAt.offset > 0 ? 1 : 0;
+    }
+    return Math.floor(windowSize / 2);
+  };
   const [renderWindow, setRenderWindow] = useState(() => {
     // Opening somewhere else than the beginning starts by framing there: the
     // rows the list will draw are the rows it will ask for.
     const openAt = scrolled ?? defaultScrolled;
-    const start = typeof openAt === "number" ? openAt - Math.floor(renderBudget / 2) : 0;
+    const start = typeof openAt === "number" ? openAt - rowsAboveOpening(openAt, renderBudget) : 0;
     const startClamped = start < 0 ? 0 : start;
     return {
       start: startClamped,
@@ -73169,8 +73368,12 @@ const useListScrollSync = ({
     // Held somewhere it has not reached yet: what the window frames right now
     // is not what it will frame, so nothing should be fetched for it.
     listRows.holdPending = scrolledWanted !== "start" && scrolledWanted !== undefined;
+    // Zero until the runs have rendered — they count their rows as they do,
+    // after the list — which is not a collection fitting in the window: it is
+    // one whose end is not known yet, and the window then frames the row the
+    // list opens on, already in the first commit.
     const total = listRows.totalSignal.peek();
-    if (total <= renderBudget) {
+    if (total > 0 && total <= renderBudget) {
       // The whole collection is what the list draws: wherever in it the list is
       // held, the window is already its place. Nowhere to move to means nothing
       // to wait for — a hold left standing here is a list that never asks for
@@ -73178,21 +73381,21 @@ const useListScrollSync = ({
       listRows.holdPending = false;
       return;
     }
-    const half = Math.floor(renderBudget / 2);
+    const above = rowsAboveOpening(scrolledWanted, renderBudget);
     let wantedStart = null;
     if (scrolledWanted === "end") {
       wantedStart = total - renderBudget;
     } else if (typeof scrolledWanted === "number") {
-      wantedStart = scrolledWanted - half;
+      wantedStart = scrolledWanted - above;
     } else if (scrolledWanted && scrolledWanted.id !== undefined) {
       const rowIndex = listRows.locateRow(scrolledWanted.id);
       if (rowIndex !== null) {
-        wantedStart = rowIndex - half;
+        wantedStart = rowIndex - above;
       } else if (typeof scrolledWanted.index === "number") {
         // The row has not come back yet, but where it stood is known: near
         // enough to frame, and to put the scrollbar roughly where it will end
         // up rather than at the top.
-        wantedStart = scrolledWanted.index - half;
+        wantedStart = scrolledWanted.index - above;
       }
     }
     if (wantedStart === null) {
@@ -73201,12 +73404,12 @@ const useListScrollSync = ({
       // back — the run asks for it by name (see useRequestMissing).
       return;
     }
+    if (total > 0 && wantedStart + renderBudget > total) {
+      wantedStart = total - renderBudget;
+    }
     if (wantedStart < 0) {
       wantedStart = 0;
     }
-    if (wantedStart + renderBudget > total) {
-      wantedStart = total - renderBudget;
-    }
     const {
       start,
       end
@@ -73543,8 +73746,8 @@ const useListScrollSync = ({
           end
         } = renderWindowRef.current;
         if (rowIndex < start || rowIndex >= end) {
-          const half = Math.floor((end - start) / 2);
-          const wantedStart = rowIndex - half < 0 ? 0 : rowIndex - half;
+          const above = rowsAboveOpening(scrolledWanted, end - start);
+          const wantedStart = rowIndex - above < 0 ? 0 : rowIndex - above;
           updateRenderWindow(wantedStart, wantedStart + (end - start), `opening on row ${scrolledWanted.id}`);
           return;
         }
@@ -73590,6 +73793,15 @@ const useListScrollSync = ({
     }
   };
   useLayoutEffect(placeWhereHeld);
+  // Held on a row of a list scrolling the document: where the document goes is
+  // this list's to say, measured on the row, not the url's offset in pixels
+  // (see holdDocumentScroll).
+  useLayoutEffect(() => {
+    if (!heldSomewhere || getScroller() !== document.scrollingElement) {
+      return undefined;
+    }
+    return holdDocumentScroll();
+  }, [heldSomewhere, scrollerElResolved]);
   // What to do when the list's own geometry moves under it, kept fresh for the
   // observer below (which is installed once).
   const onGeometryChangeRef = useRef(null);
@@ -73632,31 +73844,40 @@ const useListScrollSync = ({
   // Where the list was at the last thing that moved it. Kept whether anyone
   // asked for it or not: it is what a resize needs to put things back.
   const positionRef = useRef(null);
+  const captureListAnchor = countVisible => captureScrollAnchor({
+    scrollerEl: getScroller(),
+    listEl: getListEl(),
+    items: listRows.visibleItemsSignal.peek(),
+    horizontal,
+    countVisible
+  });
+  // Said from where the row lands on its own, and with `visibleCount`: the
+  // rows on screen from that one on, which is what a list given this position
+  // back draws first (see ListUI).
+  const toScrolledPosition = position => {
+    const rowEl = findRowElement(getListEl(), position.id);
+    return {
+      id: position.id,
+      index: position.index,
+      offset: position.offset - getRowScrollInset(getScroller(), rowEl, horizontal),
+      visibleCount: position.visibleCount
+    };
+  };
   const reportPosition = () => {
     if (!ref.current) {
       return;
     }
-    const position = captureScrollAnchor({
-      scrollerEl: getScroller(),
-      listEl: getListEl(),
-      items: listRows.visibleItemsSignal.peek(),
-      horizontal
-    });
+    const remember = rememberScrollRef.current;
+    const onScrolledChange = onScrolledChangeRef.current;
+    const position = captureListAnchor(remember || Boolean(onScrolledChange));
     if (!position) {
       return;
     }
     positionRef.current = position;
-    const remember = rememberScrollRef.current;
-    const onScrolledChange = onScrolledChangeRef.current;
     if (!remember && !onScrolledChange) {
       return;
     }
-    const rowEl = findRowElement(getListEl(), position.id);
-    const scrolledNow = {
-      id: position.id,
-      index: position.index,
-      offset: position.offset - getRowScrollInset(getScroller(), rowEl, horizontal)
-    };
+    const scrolledNow = toScrolledPosition(position);
     if (remember) {
       rememberScrollerPosition(listId, scrolledNow);
     }
@@ -73664,6 +73885,20 @@ const useListScrollSync = ({
       onScrolledChange(scrolledNow);
     }
   };
+  // Nothing scrolled, yet what is on screen changed: the list has just been
+  // laid out, its rows have arrived, one of them grew. A list read where it
+  // opened would otherwise come back with nothing kept — opening again as a
+  // fresh arrival does, all of its window drawn in the first commit instead of
+  // the rows that were on screen. Kept, and told to nobody: nobody scrolled.
+  const rememberPosition = () => {
+    if (!rememberScrollRef.current || !ref.current) {
+      return;
+    }
+    const position = captureListAnchor(true);
+    if (position) {
+      rememberScrollerPosition(listId, toScrolledPosition(position));
+    }
+  };
   // Leaving: with its page, or alone (see forgetScrollerUnlessPageLeft).
   useLayoutEffect(() => {
     return () => {
@@ -73689,6 +73924,7 @@ const useListScrollSync = ({
       // list which has outgrown a bounded ancestor stops holding on to the
       // page.
       resolveScroller();
+      rememberPosition();
       // Two things resize here, and they call for opposite answers. The LIST
       // growing is its own content settling: only a list holding itself
       // somewhere cares (the end it aims at has moved), and a list the user is
@@ -74477,12 +74713,15 @@ const getRowName = rowEl => rowEl.getAttribute("navi-list-item-real");
 // the list is rebuilt around it. Read off the rows' own boxes, not by
 // hit-testing the screen: a scrolling list takes its rows out of hit-testing
 // (see the navi-scrolling rule in the css above), and the scroll event is
-// precisely when this is asked.
+// precisely when this is asked. `countVisible` adds how many rows are on
+// screen from that one on: what a list coming back there has to draw before
+// anything else (see the first paint in ListUI).
 const captureScrollAnchor = ({
   scrollerEl,
   listEl,
   items,
-  horizontal
+  horizontal,
+  countVisible
 }) => {
   if (!scrollerEl || !listEl) {
     return null;
@@ -74518,6 +74757,9 @@ const captureScrollAnchor = ({
       offset
     };
     if (offset >= 0) {
+      if (countVisible) {
+        anchor.visibleCount = countRowsStartingBefore(rowEls, i, range.to, horizontal);
+      }
       return anchor;
     }
     // The row under the top of the view starts above it. Good enough to hold
@@ -74526,10 +74768,26 @@ const captureScrollAnchor = ({
     // top" reads, and can be drawn. Keep looking; this one is the fallback.
     if (!fallbackAnchor) {
       fallbackAnchor = anchor;
+      if (countVisible) {
+        anchor.visibleCount = countRowsStartingBefore(rowEls, i, range.to, horizontal);
+      }
     }
   }
   return fallbackAnchor;
 };
+// How many of the rows from `fromIndex` on start before `to` along the scroll
+// axis — the ones on screen, when `to` is where the view ends.
+const countRowsStartingBefore = (rowEls, fromIndex, to, horizontal) => {
+  let index = fromIndex;
+  while (index < rowEls.length) {
+    const rect = rowEls[index].getBoundingClientRect();
+    if ((horizontal ? rect.left : rect.top) >= to) {
+      break;
+    }
+    index++;
+  }
+  return index - fromIndex;
+};
 // The part of the list that is on screen, along the scrolling axis. Both edges
 // matter: the scroller may be larger than the list (scroller="parent") as well
 // as smaller (the list scrolls inside its own box).
@@ -76897,7 +77155,7 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   are skeletons, the others hold their room. `0` says the list is already
  *   known to be empty: the empty `fallback` shows right away rather than an
  *   empty frame.
- * @param {"start"|"end"|number|{id: string, offset?: number}} [props.defaultScrolled="start"]
+ * @param {"start"|"end"|number|{id: string, index?: number, offset?: number, visibleCount?: number}} [props.defaultScrolled="start"]
  *   Where the list opens, after which the user owns the scroll — unless it is
  *   being come back to (see `scrollResetOnNavigation`). `"end"` is a
  *   thread read backwards — the last rows are the ones to show, and the ones
@@ -76909,8 +77167,10 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   the screen it was saved on. `offset: 0` is where a `scrollIntoView()` puts
  *   it — in front of the fixed bar the scroller gives room for, below the
  *   sticky header and the group label the row lives under — so nothing of that
- *   room has to be restated as a number by whoever asks.
- * @param {"start"|"end"|number|{id: string, offset?: number}} [props.scrolled]
+ *   room has to be restated as a number by whoever asks. The `index` and
+ *   `visibleCount` it also hands out say where to aim before the row is found,
+ *   and how many rows to draw before the first paint (see `renderBudget`).
+ * @param {"start"|"end"|number|{id: string, index?: number, offset?: number, visibleCount?: number}} [props.scrolled]
  *   The same, but held: the list goes back there every time this changes, even
  *   after the user has scrolled — the caller owns where the list is (see
  *   `defaultScrolled` for the uncontrolled form, and `open`/`defaultOpen`
@@ -76921,12 +77181,12 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   In every form the list holds itself there while it is still finding out
  *   how many rows there are and how tall one is, and lets go the moment the
  *   user reaches for the list.
- * @param {(scrolled: {id: string, index: number, offset: number}) => void} [props.onScrolledChange]
+ * @param {(scrolled: {id: string, index: number, offset: number, visibleCount: number}) => void} [props.onScrolledChange]
  *   Where the list is, as the user scrolls: the row at the top of the view and
  *   how far below the place a row lands on its own (see `defaultScrolled`) it
- *   starts. Keep it to come back to it
- *   later through `scrolled`/`defaultScrolled` — an index would not do, since
- *   rows get inserted while a list is being read.
+ *   starts, and how many rows are on screen from that one on. Keep it whole to
+ *   come back to it later through `scrolled`/`defaultScrolled` — an index alone
+ *   would not do, since rows get inserted while a list is being read.
  * @param {number|{initial: number, after: number}} [props.renderBudget=100]
  *   How many rows of a `<List.Items>` run are in the DOM at once: the render
  *   window, which slides as the user scrolls while fillers hold the room of
@@ -76938,11 +77198,15 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   once, with room for that lookahead — the list warns below 30, and when a
  *   budget leaves fewer than two rows beyond the screen.
  *
- *   `{ initial, after }` for a list drawn in the click that opens it (a popup):
- *   `initial` rows in the commit the browser paints first — about what a phone
- *   screen shows — and `after` from the paint on, where the floor of 30
- *   applies. The runs ask their source for `after` rows from the start, so the
- *   first picture costs no second request.
+ *   `{ initial, after }` for a list whose first picture is taken as it is
+ *   built — drawn in the click that opens a popup, or in the update callback
+ *   of a route transition bringing its page back: `initial` rows in the commit
+ *   the browser paints first — about what a phone screen shows — counted from
+ *   the row the list opens on, and `after` from the paint on, around it, where
+ *   the floor of 30 applies. Opening on a position that says how many rows were
+ *   on screen (`visibleCount`, see `onScrolledChange`) draws those first,
+ *   whatever `initial` says. The runs ask their source for `after` rows from
+ *   the start, so the first picture costs no second request.
  * @param {number} [props.virtualItemSize]
  *   The size of one row along the scroll axis, in px, when every row has the
  *   same: what the fillers are sized with and what a scroll position is
@@ -77412,10 +77676,10 @@ const useBadgeRegistry = (children, enabled) => {
  *   list renders nothing at all. In a <Picker> this is the only placeholder
  *   the user gets — a picker given a `ui` does not draw its own — so pass the
  *   placeholder text: `fallback="Select skills…"`. Plain text is the right
- *   choice there: it reads at the picker's size, in the placeholder color the
- *   picker gives its empty value slot, and the box stays the same height. A
- *   transparent <Badge> matches the slot to the pixel instead, at the price of
- *   badge-sized text. See docs/badge_list.md.
+ *   choice there: it reads at the picker's size, in the normal text color (a
+ *   caller's `ui` is never greyed as a placeholder), and the box stays the same
+ *   height. A transparent <Badge> matches the slot to the pixel instead, at the
+ *   price of badge-sized text. See docs/typography.md#badgelist.
  * @param {boolean} [shrinkWrap]
  *   Narrows the list down to its widest row so the last row isn't ragged.
  *   Defaults to true inside a <Picker> — the trigger draws a border around the
@@ -79616,8 +79880,8 @@ const PickerFirstResolver = props => {
  *   filter", "anywhere"), so its empty look is the caller's. A `ui` must
  *   therefore say on its own that the picker is empty, and take the same room
  *   empty as it does filled. A <BadgeList> gets both from its `fallback` — the
- *   placeholder text, as plain text, see docs/badge_list.md. `"default"` draws
- *   nothing in the slot at all.
+ *   placeholder text, as plain text, see docs/typography.md#badgelist.
+ *   `"default"` draws nothing in the slot at all.
  *
  *   Under `variant="icon"` there is no value to draw, so this IS the trigger:
  *   left out it is the icon the right slot would have shown (`rightSlotIcon`,