@jsenv/navi 0.29.67 → 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.
@@ -21810,6 +21820,244 @@ const updateDocumentState = (value) => {
   documentStateSignal.value = value;
 };
 
+/**
+ * The document's rendering, held for the one frame a view transition needs.
+ *
+ * The browser does not take the picture of the page being left when a
+ * transition is ASKED for — it takes it at the next frame, just before running
+ * the update callback. Preact renders sooner than that, in a microtask: so a
+ * change nobody asked for (a tab pressed, the back button) has already reached
+ * the DOM when the picture is taken, and the picture is of the page ARRIVING.
+ * Both sides of the animation then show it, and one watches a page slide onto
+ * itself.
+ *
+ * So what Preact has queued waits until the update callback, which is the
+ * moment the API is built around — the change belongs inside it. The whole
+ * document is held: it is about to be frozen under a picture anyway.
+ *
+ * ONE hold for the whole document, whoever animates. The hold is a wrapper
+ * around Preact's `options.debounceRendering`, and two of them installed
+ * independently restore each other in the wrong order when they let go — every
+ * render queued in between is then handed to a wrapper nobody will ever
+ * release. Everything that photographs a navigation (RouteTravel's box, a
+ * route transition) must therefore hold through this module, never through a
+ * wrapper of its own.
+ */
+
+
+let renderingHold = null;
+const holdRendering = () => {
+  if (renderingHold) {
+    return renderingHold.release;
+  }
+  const debounceRenderingBefore = options.debounceRendering;
+  const hold = {
+    render: null,
+    waiting: [],
+    release: () => {
+      // Only the hold that is still standing may be given back: a holder
+      // releasing after another has taken over must not let go of what it
+      // does not hold.
+      if (renderingHold !== hold) {
+        return;
+      }
+      renderingHold = null;
+      options.debounceRendering = debounceRenderingBefore;
+      const { render, waiting } = hold;
+      hold.render = null;
+      hold.waiting = [];
+      if (render) {
+        render();
+      }
+      for (const wait of waiting) {
+        wait();
+      }
+    },
+  };
+  renderingHold = hold;
+  options.debounceRendering = (render) => {
+    hold.render = render;
+  };
+  return hold.release;
+};
+
+// Anything else that must not happen before the picture is taken, and the
+// scroll is the other one: a page one arrives at starts at its top, and the
+// document put back to its top while the page being left is still on screen is
+// a page that has ALREADY jumped when the picture is taken. Worse, the browser
+// paints what the new offset shows and nothing else, so the picture keeps only
+// the band it had already painted — the page being left is then seen in
+// fragments, whatever the movement does afterwards.
+//
+// Run at once when nobody is photographing anything, which is the common case
+// and must stay free.
+const whenRenderingResumes = (callback) => {
+  if (!renderingHold) {
+    callback();
+    return;
+  }
+  renderingHold.waiting.push(callback);
+};
+
+// The hold a navigation takes on its way in — from before its first write,
+// because by the time a route announces that it matches, Preact has already
+// been told and the render is queued; a hold taken then is a hold taken too
+// late. Kept here until whoever animates the change takes it over, or the
+// navigation turns out to be one nobody animates.
+let routingRenderingHold = null;
+const holdRenderingForRouting = () => {
+  routingRenderingHold = holdRendering();
+};
+// Nobody had a picture to take: a page held for a change it does not animate
+// is a page that stutters for nothing.
+const releaseRoutingRenderingHold = () => {
+  const release = routingRenderingHold;
+  routingRenderingHold = null;
+  if (release) {
+    release();
+  }
+};
+// An animator takes the navigation's hold as its own — taking another would be
+// taking a hold on a page that is holding still — or takes a fresh one when
+// the change it animates is not a navigation.
+const takeoverRoutingRenderingHold = () => {
+  const release = routingRenderingHold || holdRendering();
+  routingRenderingHold = null;
+  return release;
+};
+
+/**
+ * A container has put its page on screen — or as much of it as it can.
+ *
+ * A route matching is a signal changing, and the page it selects reaches the
+ * DOM only once Preact has rendered — an unknown number of passes later, in an
+ * unknown number of microtasks. Anyone who needs the page as it IS rather than
+ * as it has been decided (a travel about to have its picture taken by the
+ * browser, see route_travel.jsx) waits for this instead of counting.
+ *
+ * A page waiting on data is announced too, by the boundary showing its loading
+ * state (see Loading in use_async_data.jsx): what the container could put on
+ * screen is what the browser is about to take a picture of, and a page that
+ * cannot render yet would otherwise be waited on until the transition dies of
+ * it. It lives in a module of its own for that: the async layer says it as much
+ * as the router does, and neither can import the other.
+ */
+const [publishRouteRender, observeRouteRender] = createPubSub();
+
+/**
+ * Where a page was left, given back when one comes back to it.
+ *
+ * The browser does this on its own, and gets it wrong here for a reason that
+ * has nothing to do with it: it puts the offset back at the instant the entry
+ * changes, when the document still holds the page being LEFT. A position
+ * further down than that page is tall is clamped to its bottom and lost — so
+ * coming back to a long page from a short one lands short, and the deeper one
+ * was, the more is missing.
+ *
+ * So the browser is told to stop (`scrollRestoration = "manual"`) and the
+ * position is put back once the page one is coming back to is really there —
+ * through the same wait as everything else that must not happen before the
+ * picture of a transition is taken (see rendering_hold.js): restored after the
+ * picture, the page arriving would be photographed at the top and seen jumping
+ * from it.
+ *
+ * Kept per URL rather than per history entry: an entry has no name of its own
+ * that survives a reload, and two entries on the same URL are the same place
+ * to a reader. Kept in the session too, so a reload lands where the browser
+ * would have landed — the flag above is a promise to do the whole job.
+ *
+ * What is NOT covered, and cannot be from here: a page whose height depends on
+ * something still loading. Its content is not there at the moment it is put
+ * back, so a position beyond what has arrived is clamped as before. Only the
+ * page knows when it is whole.
+ */
+
+
+const STORAGE_KEY = "navi_scroll_positions";
+
+const positionByUrl = new Map();
+const readStoredPositions = () => {
+  let stored;
+  try {
+    stored = window.sessionStorage.getItem(STORAGE_KEY);
+  } catch {
+    // A session storage that refuses to answer (a private window, a policy) is
+    // not a reason to lose the positions of THIS session.
+    return;
+  }
+  if (!stored) {
+    return;
+  }
+  try {
+    for (const [url, position] of Object.entries(JSON.parse(stored))) {
+      positionByUrl.set(url, position);
+    }
+  } catch {
+    // Something else wrote there, or it was truncated.
+  }
+};
+const storePositions = () => {
+  try {
+    window.sessionStorage.setItem(
+      STORAGE_KEY,
+      JSON.stringify(Object.fromEntries(positionByUrl)),
+    );
+  } catch {
+    // Full, or refused: the session is the only thing lost.
+  }
+};
+
+let installed = false;
+const installScrollRestoration = () => {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  if (!("scrollRestoration" in window.history)) {
+    return;
+  }
+  window.history.scrollRestoration = "manual";
+  readStoredPositions();
+  // Read as it happens rather than when leaving: a traverse changes the url
+  // before anything here is told, so a position read then would be read for
+  // the wrong page.
+  window.addEventListener(
+    "scroll",
+    () => {
+      positionByUrl.set(window.location.href, {
+        x: window.scrollX,
+        y: window.scrollY,
+      });
+    },
+    { passive: true },
+  );
+  window.addEventListener("pagehide", storePositions);
+  // What a reload asks for, now that the browser has been told not to do it.
+  // Once, and at the first render of a route: the position is only meaningful
+  // once there is a page under it.
+  const positionOnLoad = positionByUrl.get(window.location.href);
+  if (positionOnLoad && (positionOnLoad.x || positionOnLoad.y)) {
+    const stopListening = observeRouteRender(() => {
+      stopListening();
+      scrollTo(positionOnLoad);
+    });
+  }
+};
+
+// Nothing to put back is not the same as putting back the top: a page arrived
+// at for the first time is startAtTop's business, and this must not step on it.
+const restoreScrollPosition = (url) => {
+  const position = positionByUrl.get(new URL(url, window.location.href).href);
+  if (!position) {
+    return;
+  }
+  scrollTo(position);
+};
+
+const scrollTo = ({ x, y }) => {
+  window.scrollTo({ top: y, left: x, behavior: "instant" });
+};
+
 /**
  * A navigation is ABOUT to be applied — said before its very first write.
  *
@@ -21882,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
@@ -21943,6 +22250,7 @@ const setupBrowserIntegrationViaHistory = ({
       } else {
         window.history.replaceState(effectiveState, null, url);
       }
+      rememberEntryIsOfThisDocument();
       updateDocumentUrl(url);
       updateDocumentState(effectiveState);
     } else {
@@ -21978,7 +22286,12 @@ const setupBrowserIntegrationViaHistory = ({
       state,
     });
     if (navigationType === "push") {
-      startAtTop(url);
+      whenRenderingResumes(() => startAtTop(url));
+    } else if (navigationType === "traverse") {
+      // Where this entry was left. Waited for like the reset above, and for
+      // the same two reasons: the page has to be there to be scrolled, and a
+      // picture taken before it would be of a page at its top.
+      whenRenderingResumes(() => restoreScrollPosition(url));
     }
     executeWithCleanup(
       () => allResult,
@@ -22042,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 },
@@ -22056,6 +22375,11 @@ const setupBrowserIntegrationViaHistory = ({
     { capture: true },
   );
 
+  // The browser's own scroll restoration is taken over here rather than left
+  // to whoever navigates: it is a decision about the document, and the entry
+  // being left must be recorded from the first pixel scrolled.
+  installScrollRestoration();
+
   window.addEventListener("popstate", (popstateEvent) => {
     const url = window.location.href;
     const state = popstateEvent.state;
@@ -22074,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,
     });
   };
 
@@ -22140,13 +22468,16 @@ const setupBrowserIntegrationViaHistory = ({
 // route_travel.jsx), and resetting there would throw the reader out of a page
 // they never left.
 //
-// After the routes have been told, and that ordering is the whole subtlety:
-// the routes changing is what sets a travel off, and a travel measures the box
-// it is leaving as it stands. Reset before that and the picture of the page
-// being left is taken at the top of a page the reader was not at the top of —
-// it is then watched jumping back to its first line before it even begins to
-// leave (see holdTravelGeometry in route_travel.jsx). After pushState too, so
-// the entry being left keeps the offset it is at.
+// After the routes have been told, and after the picture of the page being
+// left has been taken — that ordering is the whole subtlety. The routes
+// changing is what sets a movement off, and a movement measures the box it is
+// leaving as it stands; put the document back to its top any earlier and the
+// picture is of a page at its first line, which the reader was not at. The
+// browser paints what the new offset shows and nothing else, so what is kept
+// of the page being left is the band it had already painted, and the movement
+// carries a fragment (see rendering_hold.js, which is where the waiting
+// happens). After pushState too, so the entry being left keeps the offset it
+// is at.
 //
 // The document, because the document is the scrollport in the common case. An
 // app that scrolls an element of its own scrolls it itself.
@@ -22227,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
@@ -36224,24 +36557,6 @@ const TYPE_CONVERTERS = {
   },
 };
 
-/**
- * A container has put its page on screen — or as much of it as it can.
- *
- * A route matching is a signal changing, and the page it selects reaches the
- * DOM only once Preact has rendered — an unknown number of passes later, in an
- * unknown number of microtasks. Anyone who needs the page as it IS rather than
- * as it has been decided (a travel about to have its picture taken by the
- * browser, see route_travel.jsx) waits for this instead of counting.
- *
- * A page waiting on data is announced too, by the boundary showing its loading
- * state (see Loading in use_async_data.jsx): what the container could put on
- * screen is what the browser is about to take a picture of, and a page that
- * cannot render yet would otherwise be waited on until the transition dies of
- * it. It lives in a module of its own for that: the async layer says it as much
- * as the router does, and neither can import the other.
- */
-const [publishRouteRender, observeRouteRender] = createPubSub();
-
 const promiseStateWeakMap = new WeakMap();
 const usePromiseAsyncData = (
   promise,
@@ -38316,89 +38631,6 @@ const RouteUI = ({
   return element;
 };
 
-/**
- * The document's rendering, held for the one frame a view transition needs.
- *
- * The browser does not take the picture of the page being left when a
- * transition is ASKED for — it takes it at the next frame, just before running
- * the update callback. Preact renders sooner than that, in a microtask: so a
- * change nobody asked for (a tab pressed, the back button) has already reached
- * the DOM when the picture is taken, and the picture is of the page ARRIVING.
- * Both sides of the animation then show it, and one watches a page slide onto
- * itself.
- *
- * So what Preact has queued waits until the update callback, which is the
- * moment the API is built around — the change belongs inside it. The whole
- * document is held: it is about to be frozen under a picture anyway.
- *
- * ONE hold for the whole document, whoever animates. The hold is a wrapper
- * around Preact's `options.debounceRendering`, and two of them installed
- * independently restore each other in the wrong order when they let go — every
- * render queued in between is then handed to a wrapper nobody will ever
- * release. Everything that photographs a navigation (RouteTravel's box, a
- * route transition) must therefore hold through this module, never through a
- * wrapper of its own.
- */
-
-
-let renderingHold = null;
-const holdRendering = () => {
-  if (renderingHold) {
-    return renderingHold.release;
-  }
-  const debounceRenderingBefore = options.debounceRendering;
-  const hold = {
-    render: null,
-    release: () => {
-      // Only the hold that is still standing may be given back: a holder
-      // releasing after another has taken over must not let go of what it
-      // does not hold.
-      if (renderingHold !== hold) {
-        return;
-      }
-      renderingHold = null;
-      options.debounceRendering = debounceRenderingBefore;
-      const { render } = hold;
-      hold.render = null;
-      if (render) {
-        render();
-      }
-    },
-  };
-  renderingHold = hold;
-  options.debounceRendering = (render) => {
-    hold.render = render;
-  };
-  return hold.release;
-};
-
-// The hold a navigation takes on its way in — from before its first write,
-// because by the time a route announces that it matches, Preact has already
-// been told and the render is queued; a hold taken then is a hold taken too
-// late. Kept here until whoever animates the change takes it over, or the
-// navigation turns out to be one nobody animates.
-let routingRenderingHold = null;
-const holdRenderingForRouting = () => {
-  routingRenderingHold = holdRendering();
-};
-// Nobody had a picture to take: a page held for a change it does not animate
-// is a page that stutters for nothing.
-const releaseRoutingRenderingHold = () => {
-  const release = routingRenderingHold;
-  routingRenderingHold = null;
-  if (release) {
-    release();
-  }
-};
-// An animator takes the navigation's hold as its own — taking another would be
-// taking a hold on a page that is holding still — or takes a fresh one when
-// the change it animates is not a navigation.
-const takeoverRoutingRenderingHold = () => {
-  const release = routingRenderingHold || holdRendering();
-  routingRenderingHold = null;
-  return release;
-};
-
 /**
  * The window two pages are seen through while one replaces the other, measured
  * once and published for the length of the movement.
@@ -38516,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
@@ -38549,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
@@ -38694,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),
@@ -38707,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),
@@ -38833,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),
@@ -38986,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) => {
@@ -39002,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();
     }
   };
 };
@@ -39030,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();
     }
   };
 };
@@ -39055,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;
@@ -39098,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
@@ -39130,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
@@ -43351,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]
@@ -43414,6 +43795,7 @@ const LinkPlain = props => {
     endIcon,
     revealOnInteraction = false,
     hrefFallback = !anchor,
+    routeTransition,
     children
   } = props;
   if (anchor && !props.id) {
@@ -43520,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;
@@ -43570,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) {
@@ -60181,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
@@ -60407,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.
@@ -60435,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();
@@ -60445,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;
@@ -60468,6 +60888,7 @@ const useItemStore = ({
         };
         request.busy = true;
         request.revalidating = revalidating;
+        debugAsk("sent");
         if (revalidating) {
           setRefreshing(true);
         }