@jsenv/navi 0.29.439 → 0.29.440

package/dist/dev/jsenv_navi.js

@@ -72732,9 +72732,16 @@ document.addEventListener(
  * progress. A write is an instant scroll, and the browser abandons for it any
  * scroll it is playing on its own, short of where that one was going: a key
  * (Home, PageDown, Space), a smooth `scrollTo` or `scrollIntoView`, the status
- * bar tap on iOS, the fling a finger leaves behind once it lifts. A scroll
- * following a hand is not abandoned: the wheel's next turn carries on, and on
- * most engines a finger keeps dragging from wherever the write left it.
+ * bar tap on iOS. A scroll following a hand is not abandoned: the wheel's next
+ * turn carries on, and on most engines a finger keeps dragging from wherever
+ * the write left it, and the fling it leaves behind once it lifts carries on
+ * from there too (Chrome under DevTools' touch emulation: flings written to at
+ * every move of a list's window went as far as flings never written to).
+ *
+ * A fling must not be taken for a scroll the browser plays on its own. A list
+ * then leaves uncorrected, for the whole fling, the room its fillers lose above
+ * the screen as its window slides: in wematch, cards jumping half a screen
+ * several times per fling.
  *
  * Not on iOS. Its finger places the content from where the drag began, so a
  * write under it is undone at the finger's next move — or, when the finger
@@ -72742,11 +72749,15 @@ document.addEventListener(
  * stops on any write during its momentum, as the status bar's scroll to the
  * top does (Safari 26.5 on the simulator: flings of 1700px stopped 130 to 340px
  * after the lift, 3 in 3; a write 50ms before the lift stopped 2 flings in 3).
- * No finger there is a hand a write could hold to. Chrome flings on through a
- * write, and loses nothing by not getting one.
- *
- * A scroll is followed from its first "scroll" event to its "scrollend", and
- * is a hand's while a finger is down, or when a wheel turned around the time it
+ * No finger there is a hand a write could hold to, nor the fling it leaves.
+ *
+ * A scroll is followed from its first "scroll" event to its "scrollend". It is
+ * a finger's while a finger is down, and still once the finger lifts if a
+ * finger moved it around the time it started or since: the fling goes on in
+ * the drag's own scroll, or in a scroll of its own that Chrome starts right
+ * after the drag's "scrollend". What counts is a scroll the finger moved, not
+ * a lift: a tap on a button calling a smooth `scrollTo` lifts a finger that
+ * moved nothing. A scroll is a wheel's when a wheel turned around the time it
  * started or since. A finger is down from its touchstart to its touchend,
  * heard on what it touched: a list removes the items scrolled out of its window
  * while the finger is still on one of them, and the touchend of a removed
@@ -72760,6 +72771,10 @@ document.addEventListener(
 // next one. A turn further from it moved nothing (a wheel at an edge) and is no
 // hand on a scroll that came from elsewhere.
 const WHEEL_REACH = 100;
+// The fling Chrome plays as a scroll of its own starts a frame or two after the
+// drag's last move (DevTools' touch emulation, 4× CPU: 12ms after the drag's
+// "scrollend").
+const FLING_REACH = 150;
 // iOS's touch handling, the one engine whose finger drops writes (see above).
 const FINGER_KEEPS_WRITES = !window.CSS.supports(
   "-webkit-touch-callout",
@@ -72769,6 +72784,7 @@ const FINGER_KEEPS_WRITES = !window.CSS.supports(
 const flightMap = new WeakMap();
 let fingersDown = 0;
 let wheelTimeStamp = -Infinity;
+let fingerScrollTimeStamp = -Infinity;
 
 /**
  * @param {Element} scrollerEl
@@ -72779,7 +72795,10 @@ const wouldInterruptScroll = (scrollerEl) => {
   if (!flight) {
     return false;
   }
-  if (fingersDown > 0) {
+  if (
+    fingersDown > 0 ||
+    fingerScrollTimeStamp > flight.timeStamp - FLING_REACH
+  ) {
     return !FINGER_KEEPS_WRITES;
   }
   if (wheelTimeStamp > flight.timeStamp - WHEEL_REACH) {
@@ -72806,6 +72825,9 @@ if ("onscrollend" in window) {
   document.addEventListener(
     "scroll",
     (e) => {
+      if (fingersDown > 0) {
+        fingerScrollTimeStamp = e.timeStamp;
+      }
       const scroller = asScroller(e.target);
       if (flightMap.has(scroller)) {
         return;
@@ -73136,7 +73158,13 @@ const createListItems = () => {
   // One, as a rule; a child that renders several items keeps them in the order
   // they first rendered, which is all it can be told.
   const ownerIdsBySlot = new Map();
+  // What each run answers about the items it holds, drawn or not: where the
+  // one of an id sits, which one sits at an index.
   const locatorByOwner = new Map();
+  // The room each item took along the scroll axis the last time it was drawn,
+  // by id: what a filler holds for it once it is not (see rememberItemRooms in
+  // list.jsx). A number per item drawn while the list is mounted.
+  const roomById = new Map();
   // The slots as the tree reads, first to last, and where each stands in it.
   // Rebuilt once a walk has changed the tree, read to place the owners.
   const slotWalk = [];
@@ -73485,6 +73513,7 @@ const createListItems = () => {
     holdViewStill: () => {},
     horizontal: false,
     virtualItemSizeSignal: null,
+    roomById,
     renderSkeleton: undefined,
     // The children a walk stands over, in order — said in one call, before any
     // of them renders, so that what a child asks next is answered against the
@@ -73516,22 +73545,33 @@ const createListItems = () => {
     // Whether any run of items lives in this list: what makes a render window
     // mean anything (see List's renderBudget).
     hasRuns: () => locatorByOwner.size > 0,
-    setItemLocator: (ownerId, locate) => {
-      locatorByOwner.set(ownerId, locate);
+    setItemLocator: (ownerId, locator) => {
+      locatorByOwner.set(ownerId, locator);
     },
     dropItemLocator: (ownerId) => {
       locatorByOwner.delete(ownerId);
     },
     // Where the item named by that id sits, asked of whoever holds it.
     locateItem: (id) => {
-      for (const locate of locatorByOwner.values()) {
-        const index = locate(id);
+      for (const locator of locatorByOwner.values()) {
+        const index = locator.indexOf(id);
         if (index !== null) {
           return index;
         }
       }
       return null;
     },
+    // The room the item at that index took when it was last drawn, or
+    // undefined: never drawn, not held, or not an item of a run.
+    roomAt: (index) => {
+      for (const locator of locatorByOwner.values()) {
+        const id = locator.idAt(index);
+        if (id !== undefined) {
+          return roomById.get(id);
+        }
+      }
+      return undefined;
+    },
     // The place the owner's items start at — read from a signal, so that the
     // owner is rendered again when it moves (see the top of this file). Asked
     // on every render, and answered without a second look for as long as the
@@ -75648,6 +75688,8 @@ const useListScrollSync = ({
   // state: the render moves it where the list is held (holdWindow) without a
   // commit of its own.
   const renderWindowRef = useRef(null);
+  // A window was asked for that no render has drawn yet (see settleWindow).
+  const windowAskedRef = useRef(false);
   const windowLeavesItemsOut = () => {
     const renderWindow = renderWindowRef.current;
     if (!renderWindow) {
@@ -75742,6 +75784,8 @@ const useListScrollSync = ({
       return;
     }
     captureAnchor();
+    // What was measured is the room of an item alone on its line.
+    listItems.roomById.clear();
     itemsPerLineRef.current = itemsPerLineNow;
     setItemsPerLine(itemsPerLineNow);
   };
@@ -75823,6 +75867,25 @@ const useListScrollSync = ({
       }
     }
   }
+  // The items about to leave the window are still drawn: the room each takes
+  // is kept, and the filler holding its place from then on holds exactly that
+  // (see VirtualFiller). Nothing above the screen then changes as the window
+  // slides, which matters most where the anchoring cannot write: a scroll in
+  // flight (see holdAnchorStill). Every item drawn is read, since any may be
+  // the next to leave. A room kept is the room of the last drawing: an item
+  // that changed since is measured again when drawn again, and the anchoring
+  // holds the view across the difference. Items laid side by side in a grid
+  // share a line, which the fillers hold at the one size.
+  const rememberItemRooms = () => {
+    if (!ref.current || itemsPerLineRef.current !== 1) {
+      return;
+    }
+    const listEl = getListEl();
+    if (!listEl) {
+      return;
+    }
+    readItemRooms(listEl, horizontal, listItems.roomById);
+  };
   const updateRenderWindow = (newStart, newEnd, reason) => {
     const {
       start,
@@ -75831,6 +75894,7 @@ const useListScrollSync = ({
     if (newStart === start && newEnd === end) {
       return null;
     }
+    rememberItemRooms();
     captureAnchor();
     debugScroll(`updateRenderWindow(${newStart}, ${newEnd}, "${reason}")`);
     const renderWindow = {
@@ -75838,6 +75902,7 @@ const useListScrollSync = ({
       end: newEnd
     };
     renderWindowRef.current = renderWindow;
+    windowAskedRef.current = true;
     setRenderWindow(renderWindow);
     return renderWindow;
   };
@@ -76249,6 +76314,20 @@ const useListScrollSync = ({
     }
     const scrollerEl = getScroller();
     if (openAt === "end") {
+      const total = listItems.totalSignal.peek();
+      const {
+        start,
+        end
+      } = renderWindowRef.current;
+      if (end < total) {
+        // The window was framed before the runs said how many items there are
+        // (see holdWindow): the end of the document is the end of a filler.
+        // Aimed at the last items first, like a named item.
+        const windowSize = end - start;
+        const wantedStart = total - windowSize < 0 ? 0 : total - windowSize;
+        updateRenderWindow(wantedStart, total, "opening at the end");
+        return;
+      }
       sendHeldScroll(horizontal ? scrollerEl.scrollWidth : scrollerEl.scrollHeight);
       return;
     }
@@ -76326,6 +76405,13 @@ const useListScrollSync = ({
     if (stage === "steady") {
       return;
     }
+    if (windowAskedRef.current) {
+      // The hold has just aimed the window where the list opens — its end, an
+      // item it found — and the next commit draws it. Sized now, the window
+      // would weigh the items there by the ones drawn here, nowhere near them:
+      // the one-line items at the start of a thread opening on its cards.
+      return;
+    }
     const initialBudget = initialBudgetRef.current;
     if (initialBudget && !paintedRef.current) {
       if (stage === "picture") {
@@ -76667,9 +76753,9 @@ const useListScrollSync = ({
     if (wouldInterruptScroll(scrollerEl)) {
       // Nobody is looking at items standing still: they are passing by, on
       // their way somewhere the browser takes them (a key, a smooth scrollTo,
-      // the status bar, a fling). The write would stop that scroll short of
-      // where it was going. Left alone, the items drawn above push the rest by
-      // `drift` while all of it moves, and the scroll lands.
+      // the status bar, a fling on iOS). The write would stop that scroll short
+      // of where it was going. Left alone, the items drawn above push the rest
+      // by `drift` while all of it moves, and the scroll lands.
       return;
     }
     scrolledByListRef.current = true;
@@ -76798,8 +76884,14 @@ const useListScrollSync = ({
       bandEnd = walkAfter(hold.index, screenSize - hold.above, pixelsOf).index;
       forward = true;
     } else {
-      bandStart = findBandStart(items, bandFrom, itemSize);
-      bandEnd = bandTo > bandFrom ? findBandEnd(items, bandTo, itemSize) : bandStart;
+      // In the room a filler holds, an item is counted at what the filler
+      // gives it.
+      const fillerSizeOf = itemSize > 0 ? index => {
+        const room = listItems.roomAt(index);
+        return room === undefined ? itemSize : room;
+      } : null;
+      bandStart = findBandStart(items, bandFrom, fillerSizeOf, total);
+      bandEnd = bandTo > bandFrom ? findBandEnd(items, bandTo, fillerSizeOf, total) : bandStart;
       forward = scrollDirectionRef.current > 0;
     }
     if (bandStart > total) {
@@ -77057,6 +77149,8 @@ const useListScrollSync = ({
     };
   }, [scrollerElResolved]);
   holdWindow();
+  // Whatever was asked for until now is what this render draws.
+  windowAskedRef.current = false;
   const {
     start: windowStart,
     end: windowEnd
@@ -77802,12 +77896,49 @@ const readWindowGeometry = (scrollerEl, listEl, horizontal) => {
     items
   };
 };
+// The room each item drawn takes along the scroll axis (see
+// rememberItemRooms): up to the next item when that one is drawn too, so that
+// what stands between them — a separator, the label of a group the next one
+// opens — is counted; its own box otherwise. A stand-in is not measured: it
+// takes the room it is given, not the room of its item.
+const readItemRooms = (listEl, horizontal, roomById) => {
+  let previous = null;
+  const keepRoom = (item, next) => {
+    if (item.id === null) {
+      return;
+    }
+    roomById.set(item.id, next && next.index === item.index + 1 ? next.from - item.from : item.to - item.from);
+  };
+  for (const itemEl of listEl.querySelectorAll(`[${LIST_ITEM_INDEX_ATTRIBUTE}]`)) {
+    if (!isOwnItem(itemEl, listEl)) {
+      continue;
+    }
+    const rect = itemEl.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) {
+      continue;
+    }
+    const item = {
+      id: getItemName(itemEl),
+      index: Number(itemEl.getAttribute(LIST_ITEM_INDEX_ATTRIBUTE)),
+      from: horizontal ? rect.left : rect.top,
+      to: horizontal ? rect.right : rect.bottom
+    };
+    if (previous) {
+      keepRoom(previous, item);
+    }
+    previous = item;
+  }
+  if (previous) {
+    keepRoom(previous, null);
+  }
+};
 // The first item the screen shows from `position` on, and the item after the
 // last one it shows up to `position` (exclusive, like the window's end). An
 // item drawn is read off its box; in the room a filler holds for items not
-// drawn, the item is counted at the size the filler gives each of them — the
-// only way a scroll position there says which item it is.
-const findBandStart = (items, position, itemSize) => {
+// drawn, each item is counted at the size the filler gives it (`sizeOf`) —
+// the only way a scroll position there says which item it is. Without a size
+// (`null`), the room a filler holds says nothing.
+const findBandStart = (items, position, sizeOf, total) => {
   let low = 0;
   let high = items.length;
   while (low < high) {
@@ -77821,29 +77952,28 @@ const findBandStart = (items, position, itemSize) => {
   const next = items[low];
   const previous = items[low - 1];
   if (!next) {
-    if (!itemSize) {
+    if (!sizeOf) {
       return previous.index + 1;
     }
-    return previous.index + 1 + Math.floor((position - previous.to) / itemSize);
+    return findIndexAfter(previous.index + 1, previous.to, position, sizeOf, total);
   }
   if (next.from <= position) {
     return next.index;
   }
   if (!previous) {
-    if (!itemSize) {
+    if (!sizeOf) {
       return next.index;
     }
-    const index = next.index - Math.ceil((next.from - position) / itemSize);
+    const index = findIndexBefore(next.index, next.from, position, sizeOf);
     return index < 0 ? 0 : index;
   }
-  if (!itemSize || next.index === previous.index + 1) {
+  if (!sizeOf || next.index === previous.index + 1) {
     // Between two items that follow each other: a separator, a group label.
     return next.index;
   }
-  const index = previous.index + 1 + Math.floor((position - previous.to) / itemSize);
-  return index < next.index ? index : next.index;
+  return findIndexAfter(previous.index + 1, previous.to, position, sizeOf, next.index);
 };
-const findBandEnd = (items, position, itemSize) => {
+const findBandEnd = (items, position, sizeOf, total) => {
   let low = 0;
   let high = items.length;
   while (low < high) {
@@ -77857,24 +77987,53 @@ const findBandEnd = (items, position, itemSize) => {
   const previous = items[low - 1];
   const next = items[low];
   if (!previous) {
-    if (!itemSize) {
+    if (!sizeOf) {
       return next.index;
     }
-    const index = next.index - Math.ceil((next.from - position) / itemSize) + 1;
-    return index < 0 ? 0 : index;
+    return findIndexBefore(next.index, next.from, position, sizeOf) + 1;
   }
   if (previous.to >= position) {
     return previous.index + 1;
   }
-  if (!itemSize || next && next.index === previous.index + 1) {
+  if (!sizeOf || next && next.index === previous.index + 1) {
     return previous.index + 1;
   }
-  const index = previous.index + 2 + Math.floor((position - previous.to) / itemSize);
+  const index = findIndexAfter(previous.index + 1, previous.to, position, sizeOf, next ? next.index : total) + 1;
   if (next && index > next.index) {
     return next.index;
   }
   return index;
 };
+// The item whose room holds `position`, the rooms laid one after the other
+// from `from` on, starting with the item at `index` — `limit` when `position`
+// is past them all.
+const findIndexAfter = (index, from, position, sizeOf, limit) => {
+  let at = from;
+  let itemIndex = index;
+  while (itemIndex < limit) {
+    const size = sizeOf(itemIndex);
+    if (at + size > position) {
+      return itemIndex;
+    }
+    at += size;
+    itemIndex++;
+  }
+  return limit;
+};
+// The same, the rooms laid back from `to`, ending with the item before the
+// one at `index` — -1 when `position` is before them all.
+const findIndexBefore = (index, to, position, sizeOf) => {
+  let at = to;
+  let itemIndex = index;
+  while (at > position) {
+    if (itemIndex === 0) {
+      return -1;
+    }
+    itemIndex--;
+    at -= sizeOf(itemIndex);
+  }
+  return itemIndex;
+};
 // How much the window holds on each side of the screen, in the budget's unit:
 // read off the items' boxes where they stand, or — while the list holds itself
 // on an item, and the screen is where that item is going to stand (see
@@ -78390,16 +78549,19 @@ const Fallback = ({
 // every item it draws must not be redrawn — every item of it — because the size
 // settled after the first commit.
 // It holds lines: the items side by side on one take its room together, and a
-// last line left short takes it all the same.
+// last line left short takes it all the same. An item the list drew before
+// takes the room it took then instead (see rememberItemRooms).
 const VirtualFiller = ({
   edge,
   itemCount,
   itemsPerLine,
+  itemsRemembered,
+  roomRemembered,
   findChunks
 }) => {
   const listItems = useContext(ListItemsContext);
   const lineSize = listItems.virtualItemSizeSignal.value;
-  const sizeToFill = Math.ceil(itemCount / itemsPerLine) * lineSize;
+  const sizeToFill = Math.ceil(itemCount / itemsPerLine) * lineSize - itemsRemembered * lineSize / itemsPerLine + roomRemembered;
   // A filler resizing moves what stands below it — the items on screen, when it
   // holds the room of items above them — and it resizes in a commit of its own
   // when the item size settles after the list has rendered: the list puts its
@@ -78417,14 +78579,14 @@ const VirtualFiller = ({
     "navi-virtual-filler": edge,
     "aria-hidden": true,
     style: {
-      "--size-to-fill": `${sizeToFill}px`,
-      "--x-find-line-size": findChunks ? `${lineSize / itemsPerLine}px` : undefined
+      "--size-to-fill": `${sizeToFill}px`
     },
     children: findChunks && findChunks.map(chunk => jsx("div", {
       className: "navi_list_find_stand_in",
       hidden: "until-found",
       style: {
-        "--x-find-line-count": chunk.to - chunk.from
+        "--x-find-line-count": chunk.to - chunk.from,
+        "--x-find-line-size": `${chunk.room === undefined ? lineSize / itemsPerLine : chunk.room}px`
       },
       children: chunk.text
     }, `${chunk.from}_${chunk.to}`))
@@ -79317,16 +79479,51 @@ const useRunItems = (store, {
   // Where an item named from outside actually sits. Only the run can answer:
   // items it holds but does not draw are nowhere else — a list only knows the
   // items it has drawn (they register themselves, see ListItemUI).
-  listItems.setItemLocator(ownerId, id => {
-    let found = null;
-    store.eachHeld((item, rank) => {
-      const itemIndex = indexOfRank(rank);
-      if (found === null && idOf(item, itemIndex) === id) {
-        found = itemIndex;
+  const idAt = itemIndex => {
+    if (itemIndex < runStart || itemIndex >= runEnd) {
+      return undefined;
+    }
+    const item = getItemAt(itemIndex);
+    return item === undefined ? undefined : idOf(item, itemIndex);
+  };
+  listItems.setItemLocator(ownerId, {
+    indexOf: id => {
+      let found = null;
+      store.eachHeld((item, rank) => {
+        const itemIndex = indexOfRank(rank);
+        if (found === null && idOf(item, itemIndex) === id) {
+          found = itemIndex;
+        }
+      });
+      return found;
+    },
+    idAt
+  });
+  // The room an item took when the list last drew it (see rememberItemRooms),
+  // or undefined: a filler holds an item it never drew at the item size.
+  const roomOf = itemIndex => {
+    const id = idAt(itemIndex);
+    return id === undefined ? undefined : listItems.roomById.get(id);
+  };
+  const readRemembered = (from, to) => {
+    const remembered = {
+      room: 0,
+      count: 0
+    };
+    if (listItems.roomById.size === 0) {
+      return remembered;
+    }
+    let itemIndex = from;
+    while (itemIndex < to) {
+      const room = roomOf(itemIndex);
+      if (room !== undefined) {
+        remembered.room += room;
+        remembered.count++;
       }
-    });
-    return found;
-  });
+      itemIndex++;
+    }
+    return remembered;
+  };
   useLayoutEffect(() => {
     return () => {
       listItems.dropItemLocator(ownerId);
@@ -79502,7 +79699,9 @@ const useRunItems = (store, {
   };
   // The text of the items a filler stands for, cut in chunks aligned on the
   // run's own ranks: the window sliding changes the chunk at its edge and
-  // leaves the others as they are.
+  // leaves the others as they are. A chunk's lines are all as tall as the
+  // room its items take in the filler, so it also ends where that room
+  // changes: a match is then found where its item will be drawn.
   const getFindChunks = (from, to) => {
     if (!findText) {
       return null;
@@ -79512,10 +79711,11 @@ const useRunItems = (store, {
     while (chunkFrom < to) {
       const chunkIndex = Math.floor(rankOf(chunkFrom) / FIND_CHUNK_ITEM_COUNT);
       const alignedTo = indexOfRank((chunkIndex + 1) * FIND_CHUNK_ITEM_COUNT);
-      const chunkTo = alignedTo < to ? alignedTo : to;
+      const chunkEnd = alignedTo < to ? alignedTo : to;
+      const room = roomOf(chunkFrom);
       const lines = [];
       let lineIndex = chunkFrom;
-      while (lineIndex < chunkTo) {
+      while (lineIndex < chunkEnd && roomOf(lineIndex) === room) {
         const item = getItemAt(lineIndex);
         // An item not held has nothing to find, but keeps its line: the items
         // after it stay at their place.
@@ -79524,10 +79724,11 @@ const useRunItems = (store, {
       }
       chunks.push({
         from: chunkFrom,
-        to: chunkTo,
+        to: lineIndex,
+        room,
         text: lines.join("\n")
       });
-      chunkFrom = chunkTo;
+      chunkFrom = lineIndex;
     }
     return chunks;
   };
@@ -79536,10 +79737,13 @@ const useRunItems = (store, {
   // one run, and what sits before or after it (a header, items given one by
   // one) is not virtualized at all.
   if (windowFrom > runStart) {
+    const remembered = readRemembered(runStart, windowFrom);
     nodes.push(jsx(VirtualFiller, {
       edge: "before",
       itemCount: windowFrom - runStart,
       itemsPerLine: itemsPerLine,
+      itemsRemembered: remembered.count,
+      roomRemembered: remembered.room,
       findChunks: getFindChunks(runStart, windowFrom)
     }, "navi-list-filler-before"));
   }
@@ -79641,10 +79845,13 @@ const useRunItems = (store, {
   }
   closeGroup();
   if (runEnd > windowTo) {
+    const remembered = readRemembered(windowTo, runEnd);
     nodes.push(jsx(VirtualFiller, {
       edge: "after",
       itemCount: runEnd - windowTo,
       itemsPerLine: itemsPerLine,
+      itemsRemembered: remembered.count,
+      roomRemembered: remembered.room,
       findChunks: getFindChunks(windowTo, runEnd)
     }, "navi-list-filler-after"));
   }
@@ -80588,19 +80795,20 @@ const ListResolved = /*#__PURE__*/createComponentResolver([ListFirstResolver, Li
  *   source for is a page (see `<List.Items pageSize>`), whatever either says,
  *   so the first picture costs no second request.
  * @param {number} [props.virtualItemSize]
- *   The room an item not drawn is held at, in px along the scroll axis: what
- *   the fillers hold for each item outside the render window, what a scroll
- *   position inside them is read with, and the least an item on its way takes
- *   (see `renderSkeleton`). Left out, it is the average of the items measured
- *   so far — once when the list mounts, again when a popup around it opens,
- *   and after each commit while items are held off screen. Given, it is the
- *   worst case: the size every item has, or, in a list whose items differ, the
- *   smallest an item can be (a thread of one-line items and cards: the
- *   one-line size) — an item guessed too small builds one more, an item
- *   guessed too big leaves a blank (see docs/scroll.md, "What the list knows,
- *   and what it guesses"). The items drawn are measured either way: the render
- *   window is sized on them. In a grid (`columns`), the size is a line's: a
- *   card's, which the items side by side on it share.
+ *   The room an item never drawn is held at, in px along the scroll axis: what
+ *   the fillers hold for it outside the render window, what a scroll position
+ *   inside them is read with, and the least an item on its way takes (see
+ *   `renderSkeleton`). An item the list has drawn is held at the room it took
+ *   then. Left out, it is the average of the items measured so far — once when
+ *   the list mounts, again when a popup around it opens, and after each commit
+ *   while items are held off screen. Given, it is the worst case: the size
+ *   every item has, or, in a list whose items differ, the smallest an item can
+ *   be (a thread of one-line items and cards: the one-line size) — an item
+ *   guessed too small builds one more, an item guessed too big leaves a blank
+ *   (see docs/scroll.md, "What the list knows, and what it guesses"). The items
+ *   drawn are measured either way: the render window is sized on them. In a
+ *   grid (`columns`), the size is a line's: a card's, which the items side by
+ *   side on it share, and the lines drawn are held at it too.
  * @param {"self"|"parent"|"document"|Element|{current: Element}} [props.scroller="self"]
  *   Which box scrolls — and with it, which box the render window follows and
  *   which box a scroll position is read from (`onScrolledChange`). `"self"`