@luigisbox/luma 0.1.0 → 0.3.0

package/src/widgets/listing/element.ts

@@ -24,6 +24,7 @@ import { firstRowCount, firstRowImages, imageHelpers, imageOf, preloadImages, se
 import { view } from '../../core/templates';
 import { afterFrame, isPromise } from '../../core/scheduler';
 import { onUrlChange } from '../../core/sense';
+import { onOwnBack } from '../../core/entries';
 import { layered, setCss } from '../../core/styles';
 import type { Takeover } from '../../core/takeover';
 import { canon, pageKey, writeUrl } from '../../core/url';
@@ -36,8 +37,9 @@ import { flowKey, notAbove, onQuickLanded, quickChannel } from './flow';
 import { firstPages, targetOf, thrifty, watchIntent } from './intent';
 import type { Page } from '../../api';
 import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, viewport, type ListingView, type SsrState } from './view';
-import { dropStash, readStash, writeStash, type Stash } from './stash';
-import { keepViewport, leavingLink, nearEnd, preconnectImages, restoreScroll, scrollSpot } from './instant';
+import { dropStash, peekStash, readStash, writeStash, type Stash } from './stash';
+import { adoptScroll, holdScroll, keepViewport, leavingLink, nearEnd, preconnectImages, releaseScroll, restoreScroll, scrollSpot } from './instant';
+import { watch } from '../../core/tiles';
 
 /** A re-render answered within DIM_MS (no dim shown) fades its list in from this opacity, over FADE_MS. */
 const FADE_FROM = 0.6;
@@ -198,7 +200,10 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   let rehearsed = false;
   if (!seeded.size) {
     stashed = readStash(route.id, location.href);
-    if (stashed) {
+    if (stashed?.sr) adoptScroll();
+    // Too old to render from: where the shopper was only (the results are asked for as on any load).
+    if (stashed?.stale) mark(`${route.id} back: stash too old, its scroll only`);
+    else if (stashed) {
       seeded.set(pageKey(location.href), stashed.query);
       cache.set(keyOf(stashed.query), stashed.result);
       mark(`${route.id} from stash (${stashed.kind}, ${stashed.result.hits.length} hits)`);
@@ -307,6 +312,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     private drawnUrl: URL | null = null;
     /** Facet groups the shopper opened or closed, and the text in a group's search box, for the visit. */
     private groupOpen: Record<string, boolean> = {};
+    /** Groups shown open for their selection in the visit (ListingView `kept`). */
+    private groupKept: Record<string, boolean> = {};
     private groupText: Record<string, string> = {};
     private groupSaid = 0;
     /**
@@ -316,6 +323,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      */
     private staged: UiState | null = null;
     private stagedMode = false;
+    /** Stops watching the `facetsApply` breakpoints of the open drawer (watchApply()). */
+    private unwatchApply: (() => void) | null = null;
     /** Renders started: a render in chunks stops when a newer one has started. */
     private renders = 0;
     // Accessibility (docs/ACCESSIBILITY.md, "Listings"): our status region (and
@@ -331,6 +340,14 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     private shownBefore = 0;
     /** The drawer's opener (focus goes back to it) and the attributes lent to its panel. */
     private drawerFrom: HTMLElement | null = null;
+    /**
+     * The history entry of ours that stands for the open staged drawer (the
+     * same URL; Back closes the drawer, core/entries.ts `onOwnBack`), and what
+     * waits for our own history.back() of it (an Apply's navigation).
+     */
+    private drawerEntry = false;
+    private drawerBack: (() => void) | null = null;
+    private unBack: (() => void) | null = null;
     private panelAria: ReturnType<typeof borrow> | null = null;
     /** Another state's results awaited (loading()): the timer that dims the list, and whether it has. */
     private wait: { timer: number; dimmed: boolean } | null = null;
@@ -345,7 +362,18 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
 
     /** When the page was hidden (pagehide): a restore from the back/forward cache after long is revalidated. */
     private hiddenAt = 0;
-    private onPageHide = () => void (this.hiddenAt = Date.now());
+    /** scrollY when a Back stash was last written (leave()): the page hidden from there is stashed already. */
+    private leftAt = -1;
+    private onPageHide = () => {
+      this.hiddenAt = Date.now();
+      // Left with more than the first page shown, not by a link of ours (a
+      // reload, their menu, the address bar): stashed too, so a reload within
+      // the minute shows it as left, in place, and a later load of the entry
+      // is placed by Luma (the browser's restoration landed in a first page
+      // shorter than where the shopper was). Into the back/forward cache
+      // too: it may be evicted there (then Back is a page load).
+      if (restoreOn && (this.last?.page ?? 0) > 1 && this.leftAt !== Math.round(scrollY)) this.leave();
+    };
     /**
      * Restored from the back/forward cache (pageshow, persisted): the page is as
      * the shopper left it, from memory. Our own Back restore (./stash.ts) is not
@@ -357,8 +385,14 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      */
     private onPageShow = (e: PageTransitionEvent) => {
       if (!e.persisted) return;
+      // Where the shopper was: the browser's own restoration is off for the
+      // entry (holdScroll), and iOS Safari reads scrollY 0 at this event
+      // even when it restores it. Placed again, then the browser's back on.
+      const st = peekStash(location.href);
       dropStash(location.href);
       mark(`${route.id} restored from the back/forward cache`);
+      if (st?.kind === 'back' && st.scroll && tk.state === 'ours') restoreScroll(this, st.scroll, releaseScroll);
+      else releaseScroll();
       const away = this.hiddenAt ? Date.now() - this.hiddenAt : 0;
       if (away > BFCACHE_STALE_MS && this.last && this.lastQ && this.lastQ === this.current) this.revalidate(this.lastQ, this.last, new URL(location.href), this.href);
     };
@@ -391,7 +425,11 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (!this.hasAttribute('role')) this.setAttribute('role', 'region');
       if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', t('label'));
       if (!this.hasAttribute('tabindex')) this.tabIndex = -1;
-      this.unsub = onUrlChange(() => this.resync());
+      // Moved on within this document (an SPA's navigation): its scroll is the host's again.
+      this.unsub = onUrlChange(() => (releaseScroll(), this.urlMoved(), this.resync()));
+      this.unBack ??= onOwnBack(this.onBack);
+      // Product clicks and add-to-carts on our tiles: the framework's, never a template's (core/tiles.ts).
+      watch(this, { list: `lbx_${route.id}`, global: ctx.global, results: () => this.last?.hits.map(ctx.result) ?? [] });
       this.addEventListener('click', this.onClick);
       this.addEventListener('keydown', this.onKey);
       this.addEventListener('focusout', this.onFocusOut);
@@ -399,7 +437,10 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       document.addEventListener('pointerdown', this.onOutside, true);
       addEventListener('pagehide', this.onPageHide);
       addEventListener('pageshow', this.onPageShow);
+      addEventListener('scroll', this.onScroll, { passive: true });
       if (prefetchFilters) this.intent ??= watchIntent(this, (el) => this.onIntent(el));
+      // Put back by a host re-render with its drawer open: still watched.
+      if (this.hasAttribute('data-drawer-open') && !this.unwatchApply) this.watchApply();
       // Microtask: runs before paint (no empty frame) but outside the
       // reconciler's placement pass.
       queueMicrotask(() => this.resync());
@@ -408,6 +449,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     disconnectedCallback() {
       mark(`${route.tag} disconnected`);
       this.unsub?.();
+      this.unBack?.();
+      this.unBack = null;
       this.removeEventListener('click', this.onClick);
       this.removeEventListener('keydown', this.onKey);
       this.removeEventListener('focusout', this.onFocusOut);
@@ -415,12 +458,15 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       document.removeEventListener('pointerdown', this.onOutside, true);
       removeEventListener('pagehide', this.onPageHide);
       removeEventListener('pageshow', this.onPageShow);
+      removeEventListener('scroll', this.onScroll);
       this.ctrl?.abort();
       this.ahead?.();
       this.intent?.stop();
       this.intent = null;
       this.sized?.ro.disconnect();
       this.sized = null;
+      this.unwatchApply?.();
+      this.unwatchApply = null;
       // Not the pending click: the reconciler puts this same element back after a
       // host re-render, and the click's timer then still applies it.
       this.href = ''; // re-sync if we are ever re-attached
@@ -455,26 +501,94 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (!d || !this.contains(d)) {
         // A link to another page (a product): remembered for Back.
         const away = restoreOn && leavingLink(e, this);
-        if (away) this.leave(away);
+        if (away) {
+          this.leave(away);
+          // Cancelled by a handler after ours (an SPA's router: no page load): its scroll is the host's.
+          setTimeout(() => e.defaultPrevented && releaseScroll(), 0);
+        }
         return;
       }
       e.preventDefault();
       const what = d.getAttribute('data-lbx-drawer');
       // "apply" commits what the drawer holds (staged) and closes; "close" (and the overlay) discards it.
-      if (what === 'apply') this.applyStaged();
+      if (what === 'apply') return this.applyStaged(d as HTMLElement);
       this.setDrawer(what === 'open', d as HTMLElement);
     };
 
+    /**
+     * Back on the drawer's entry: the browser's Back (the drawer closes, what
+     * it held dropped), or ours (history.back() from closing it: then what
+     * waited for it).
+     */
+    private onBack = () => {
+      const then = this.drawerBack;
+      if (then) {
+        this.drawerBack = null;
+        // After the frame: the browser restores the entry's scroll position
+        // after its popstate, which would undo the scroll to the listing's top.
+        requestAnimationFrame(() => setTimeout(then, 0));
+        return true;
+      }
+      if (!this.drawerEntry || !this.isConnected) return false;
+      this.drawerEntry = false;
+      this.setDrawer(false);
+      return true;
+    };
+
+    /**
+     * The URL moved on while the drawer is open, not by us (Back or Forward
+     * across our states in a drawer with no entry of its own, the host's
+     * navigation): the drawer closes, as the page it was over is gone.
+     */
+    private urlMoved() {
+      const href = canon(location.href);
+      if (href === this.href || href === this.wantedHref) return;
+      // Back or Forward to a state of ours: where the shopper was in it, and in the one left.
+      if (this.href) this.scrolls.set(this.href, this.y);
+      const y = this.scrolls.get(href);
+      this.restoreY = y == null ? null : { href, y };
+      if (this.hasAttribute('data-drawer-open') && !this.drawerBack) this.setDrawer(false);
+    }
+
+    /**
+     * Where the shopper was in each state of the visit left by a change of
+     * ours or a traversal (canonical href → scrollY), and the one a traversal
+     * goes back to: drawn whole (not in steps) and placed there. Bug (a
+     * bicycle shop's QA round 4, 2026-10-15): Back after a drawer filter
+     * drew the list in steps, the browser's restored scroll was clamped to
+     * the first step's short page, and Chromium's scroll anchoring kept the
+     * footer in view as the tiles went in above it.
+     */
+    private scrolls = new Map<string, number>();
+    /** scrollY as of the last scroll event (read there: a read in a popstate after the host's DOM writes forced a style and layout). */
+    private y = 0;
+    private onScroll = () => void (this.y = Math.round(scrollY));
+    private restoreY: { href: string; y: number } | null = null;
+
     /** Changes go to the drawer's held state instead of the URL: it is open, where it stages. */
     private staging() {
       return this.stagedMode && this.hasAttribute('data-drawer-open');
     }
 
-    /** The drawer's held changes, applied: one request, one history entry. */
-    private applyStaged() {
+    /**
+     * The drawer's held changes, applied: one request, one history entry
+     * (after the drawer's own entry is gone), and the listing's top in view:
+     * a new result set under a shopper far down the old one showed its
+     * middle, the count and the first tiles above the viewport.
+     */
+    private applyStaged(from?: HTMLElement) {
       const next = this.staged;
       this.staged = null;
-      if (next) this.navigate(next);
+      this.setDrawer(false, from, next ? () => (this.navigate(next), (this.topFor = this.wantedHref), this.toListTop()) : undefined);
+    }
+
+    /** The state an Apply asked for: its render brings the listing's top into view again (late layout, a smooth scroll cut short). */
+    private topFor: string | null = null;
+    /** The top of the listing in view when it is above the viewport (smooth, unless reduced motion is asked for). */
+    private toListTop() {
+      if (!this.isConnected || this.getBoundingClientRect().top >= 0) return;
+      const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+      this.scrollIntoView({ block: 'start', behavior: (reduce ? 'instant' : 'smooth') as ScrollBehavior });
     }
 
     /** The drawer's held changes dropped: it shows the applied state again. */
@@ -491,8 +605,11 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * cycles), Escape closes it, and focus goes back to the button that opened
      * it. On wide screens the same markup is a sidebar: the role is lent while
      * open only. Without a panel: the buttons' state, Escape and the way back.
+     * Where it stages, a history entry of ours stands for it while open:
+     * Back closes it (as the autocomplete's phone sheet); closing it otherwise
+     * takes the entry back first, then runs `then`.
      */
-    private setDrawer(open: boolean, from?: HTMLElement) {
+    private setDrawer(open: boolean, from?: HTMLElement, then?: () => void) {
       const was = this.hasAttribute('data-drawer-open');
       this.toggleAttribute('data-drawer-open', open);
       for (const b of this.querySelectorAll('[data-lbx-drawer="open"]')) b.setAttribute('aria-expanded', String(open));
@@ -501,6 +618,12 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (!open) this.discardStaged();
       if (open && !was) {
         this.stagedMode = atWidth(cfg.facetsApply, 'instant', viewport) === 'staged';
+        if (this.stagedMode && !this.drawerEntry)
+          try {
+            history.pushState(null, '', location.href);
+            this.drawerEntry = true;
+          } catch {}
+        this.watchApply();
         this.drawerFrom = (from?.getAttribute('data-lbx-drawer') === 'open' ? from : document.activeElement) as HTMLElement | null;
         if (panel) {
           const a = (this.panelAria = borrow(panel));
@@ -516,13 +639,51 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
           (focusables(root).find((el) => el.getAttribute('data-lbx-drawer') !== 'open') ?? (root as HTMLElement)).focus();
         });
       } else if (!open && was) {
+        this.unwatchApply?.();
+        this.unwatchApply = null;
         this.panelAria?.restore();
         this.panelAria = null;
         const back = this.drawerFrom;
         this.drawerFrom = null;
         const at = document.activeElement;
         if (back?.isConnected && (!at || at === document.body || this.contains(at))) afterFrame(() => back.focus());
+        if (this.drawerEntry) {
+          this.drawerEntry = false;
+          const done = then ?? (() => {});
+          this.drawerBack = done;
+          history.back();
+          // A Back the browser does not deliver (an entry it dropped): on after a while.
+          setTimeout(() => {
+            if (this.drawerBack !== done) return;
+            this.drawerBack = null;
+            done();
+          }, 600);
+          return;
+        }
       }
+      then?.();
+    }
+
+    /**
+     * The open drawer closes when the viewport crosses into another
+     * `facetsApply` mode (a phone rotated, a window widened): the drawer was a
+     * phone's, and what it held was never confirmed. Regression (a bicycle
+     * shop, `{ 0: 'staged', 992: 'instant' }`, 2026-10-14): a value ticked in
+     * the drawer at 820 px stayed ticked in the 992 px sidebar with the
+     * results unfiltered and no apply button there, and rotating back showed
+     * the full-screen drawer again (`data-drawer-open` had stayed). Dropping
+     * is safer than applying: the shopper never pressed Apply.
+     */
+    private watchApply() {
+      const v = cfg.facetsApply;
+      if (!v || typeof v !== 'object' || typeof matchMedia !== 'function') return;
+      const mode = atWidth(v, 'instant', viewport);
+      const lists = Object.keys(v).map(Number).filter((w) => w > 0).map((w) => matchMedia(`(min-width: ${w}px)`));
+      const on = () => {
+        if (this.hasAttribute('data-drawer-open') && atWidth(v, 'instant', viewport) !== mode) this.setDrawer(false);
+      };
+      for (const l of lists) l.addEventListener('change', on);
+      this.unwatchApply = () => lists.forEach((l) => l.removeEventListener('change', on));
     }
 
     /**
@@ -671,6 +832,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
         if (!this.inFlight) this.setBusy(false);
         return;
       }
+      if (this.href) this.scrolls.set(this.href, this.y);
+      this.restoreY = null;
       this.wanted = next;
       this.wantedHref = canon(url.href);
       // Respond first, work later: the fetch and the history write run in later
@@ -829,7 +992,15 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
             if (c.signal.aborted || this.href !== href || (p.quickPending && !notAbove(route.id, 'quick'))) return;
             mark(`${route.id} products before their facets`);
             this.message = null;
-            this.render(q, p, url);
+            // Another state of the visit shown (a filter, a sort): its sidebar
+            // stays until the new facets come, as from the intent prefetch.
+            // Bug (a bicycle shop's QA round 3, 2026-10-15): drawn with no
+            // facets, the sidebar collapsed to one group for ~250 ms and
+            // Chromium's scroll anchoring threw the page to its top.
+            const last = this.last;
+            const lq = this.lastQ;
+            const keep = last && lq && tk.state === 'ours' && visitOf(lq) === visitOf(q);
+            this.render(q, keep ? { ...p, facets: last.facets, facetsAll: last.facetsAll } : p, url);
             productsShown = true;
           });
           if (productsShown) this.quiet = true; // said with the products
@@ -915,13 +1086,27 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * The shopper follows a link to another page (a product): the listing as
      * it is, and where they are, for Back (./stash.ts). Only what is shown.
      */
-    private leave(a: HTMLAnchorElement) {
+    private leave(a?: HTMLAnchorElement) {
       if (!this.last || !this.lastQ || this.lastQ !== this.current || this.inFlight) return;
-      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a) })) mark(`${route.id} stashed for back`);
+      this.leftAt = Math.round(scrollY);
+      // The browser's own restoration off for this entry: Luma places the page after its render (holdScroll).
+      const sr = holdScroll();
+      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a), sr })) mark(`${route.id} stashed for back`);
+      else releaseScroll();
     }
 
     /** After a render: back where the shopper was (a stashed page), the next page when they near the end, the image host. */
     private afterRender(q: Query, res: ListingResult, url: URL) {
+      const back = this.restoreY;
+      if (back && back.href === this.href && !res.partial) {
+        this.restoreY = null;
+        // After the frame, with layout clean (a read now forced it: the main-thread gates).
+        if (tk.state === 'ours') afterFrame(() => this.href === back.href && restoreScroll(this, { y: back.y }));
+      }
+      if (this.topFor && this.topFor === this.href) {
+        this.topFor = null;
+        afterFrame(() => this.toListTop());
+      }
       // Whether the facets sit above the products (notAbove): read a frame
       // later, when layout is clean (the read costs only itself). Shown only.
       // The quick types likewise (notAbove), where some are shown.
@@ -953,16 +1138,19 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
           const href = this.href;
           // After the reveal (a font wait may delay it): ours must be laid out to find the tile.
           const at = (n = 0) =>
-            this.href === href && (tk.state === 'ours' ? (restoreScroll(this, st.scroll ?? { y: 0 }), mark(`${route.id} scroll restored`)) : n < 120 && requestAnimationFrame(() => at(n + 1)));
+            this.href === href && (tk.state === 'ours' ? (restoreScroll(this, st.scroll ?? { y: 0 }, releaseScroll), mark(`${route.id} scroll restored`)) : n < 120 ? requestAnimationFrame(() => at(n + 1)) : releaseScroll());
           at();
           // Silently fresh after a while away: asked again in the background,
           // re-rendered only when the results changed. A quick round trip to
           // a product shows the listing as left (a reshuffle in front of the
-          // shopper, on an API that orders ties anew, was the bug).
-          if (Date.now() - st.at > BFCACHE_STALE_MS) setTimeout(() => this.revalidate(q, st.result, url, href), 1500);
-          else mark(`${route.id} back: as left, not revalidated`);
+          // shopper, on an API that orders ties anew, was the bug). A stale
+          // stash's results were not used: these are fresh.
+          if (!st.stale) {
+            if (Date.now() - st.at > BFCACHE_STALE_MS) setTimeout(() => this.revalidate(q, st.result, url, href), 1500);
+            else mark(`${route.id} back: as left, not revalidated`);
+          }
         }
-      }
+      } else if (st) releaseScroll();
       this.ahead?.();
       this.ahead = null;
       if (skipOut) this.sizeTiles();
@@ -1128,6 +1316,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       const at = (st: UiState) => canon(route.write(new URL(location.href), st).href);
       return {
         open: this.groupOpen,
+        kept: this.groupKept,
+        keptOpen: (name) => void (this.groupKept[name] = true),
         openDefault: atWidth(cfg.facetGroups?.open, true, viewport),
         text: this.groupText,
         apply: atWidth(cfg.facetsApply, 'instant', viewport),
@@ -1268,12 +1458,13 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       const total = () => void (this.dataset.total = String(res.total));
       if (tk.state !== 'hold') total();
       const visit = JSON.stringify([q.q, q.scope]);
-      if (visit !== this.uiVisit) (this.uiVisit = visit), (this.ui = {}), (this.groupOpen = {}), (this.groupText = {}), (this.staged = null);
+      if (visit !== this.uiVisit) (this.uiVisit = visit), (this.ui = {}), (this.groupOpen = {}), (this.groupKept = {}), (this.groupText = {}), (this.staged = null);
       const d0 = performance.now();
       let data = this.dataFor(q, res, url);
       /** The scope's own time (ms): a re-render's first step goes to the next frame when the two would not fit BUDGET. */
       const dataMs = performance.now() - d0;
-      let cut: number | undefined;
+      // Back or Forward to a state with a place in it: every tile at once, so the page is as tall as it was.
+      let cut: number | undefined = this.restoreY?.href === this.href ? Infinity : undefined;
       this.drawn = data;
       // Server markup that is not hydrated (no cached result for it: its facets
       // were missing) is replaced, not rendered after.

package/src/widgets/listing/instant.ts

@@ -24,36 +24,71 @@ export const leavingLink = (e: MouseEvent, root: Element): HTMLAnchorElement | n
   return a;
 };
 
-/** The first link to `href` in root (a tile has several: its image, its title). */
-const linkTo = (root: Element, href: string) => {
-  for (const a of root.querySelectorAll<HTMLAnchorElement>('a[href]')) if (a.href === href) return a;
-  return null;
+/** A link laid out on the page: not display:none (a tile may carry a phone-only copy of a link, hidden on wider screens). */
+const shown = (a: Element) => a.getClientRects().length > 0;
+/** The links to `href` in root that are laid out (a tile has several: its image, its title, its compare links). */
+const linksTo = (root: Element, href: string) => [...root.querySelectorAll<HTMLAnchorElement>('a[href]')].filter((a) => a.href === href && shown(a));
+/** The `n`th laid-out link to `href` in root (the one followed, when it can be told), else the first. */
+const linkTo = (root: Element, href: string, n = 0) => {
+  const as = linksTo(root, href);
+  return as[n] ?? as[0] ?? null;
 };
 
-/** Where the shopper is, pinned to the link they follow (layout above it may differ on the way back). */
-export const scrollSpot = (root: Element, a: HTMLAnchorElement) => ({ y: Math.round(scrollY), href: a.href, top: Math.round((linkTo(root, a.href) ?? a).getBoundingClientRect().top) });
+/** Where the shopper was (a Back stash's `scroll`). */
+export interface Spot {
+  y: number;
+  href?: string;
+  top?: number;
+  n?: number;
+}
+
+/**
+ * Where the shopper is, pinned to the link they follow (layout above it may
+ * differ on the way back): which of the laid-out links to its href it is
+ * (`n`), and its top. Without a link (the page left otherwise), the first
+ * tile link in the viewport.
+ */
+export const scrollSpot = (root: Element, a?: HTMLAnchorElement | null): Spot => {
+  a ??= [...root.querySelectorAll<HTMLAnchorElement>('[data-lbx-list] a[href]')].find((l) => shown(l) && l.getBoundingClientRect().top >= 0) ?? null;
+  if (!a) return { y: Math.round(scrollY) };
+  const as = linksTo(root, a.href);
+  const n = as.indexOf(a);
+  const pin = n >= 0 ? a : as[0] ?? a;
+  return { y: Math.round(scrollY), href: a.href, top: Math.round(pin.getBoundingClientRect().top), ...(n > 0 ? { n } : {}) };
+};
 
 const scroll = (top: number) => scrollTo({ top, left: scrollX, behavior: 'instant' as ScrollBehavior });
 
 /**
  * Back where the shopper was: the followed link at the same place in the
- * viewport (scrollY when it is gone). Late layout above us (their images,
- * banners, fonts) moves it: followed for a while, until the shopper scrolls,
- * taps or types themselves.
+ * viewport (scrollY when it is gone; the top of the listing when scrollY
+ * would land past its end: a listing shorter than the one left, the link
+ * on a page not shown). Late layout
+ * above us (their images, banners, fonts) moves it: followed for a while,
+ * until the shopper scrolls, taps or types themselves; then `after`.
  */
-export const restoreScroll = (root: Element, s: { y: number; href?: string; top?: number }) => {
+export const restoreScroll = (root: Element, s: Spot, after?: () => void) => {
   let done = false;
+  /** The link gone and the listing too short for scrollY: its top, once decided. */
+  let short = false;
   const place = () => {
     if (done) return;
-    const a = s.href ? linkTo(root, s.href) : null;
+    const a = s.href ? linkTo(root, s.href, s.n) : null;
     if (a) {
       const d = a.getBoundingClientRect().top - (s.top ?? 0);
       if (Math.abs(d) >= 1) scroll(scrollY + d);
-    } else if (Math.abs(scrollY - s.y) >= 1) scroll(s.y);
+      return;
+    }
+    const box = root.getBoundingClientRect();
+    // A link in the listing was the place: gone, and the listing ends above where the viewport was (fewer pages than left).
+    if (!short && s.href && s.y > 0 && s.y + innerHeight > box.bottom + scrollY) short = true;
+    const y = short ? Math.max(0, Math.round(box.top + scrollY)) : s.y;
+    if (Math.abs(scrollY - y) >= 1) scroll(y);
   };
   const STOP = ['wheel', 'touchstart', 'keydown', 'pointerdown'];
   const ro = new ResizeObserver(() => place());
   const stop = () => {
+    if (!done) after?.();
     done = true;
     ro.disconnect();
     for (const t of STOP) removeEventListener(t, stop, true);
@@ -64,24 +99,49 @@ export const restoreScroll = (root: Element, s: { y: number; href?: string; top?
   setTimeout(stop, 2500);
 };
 
+/**
+ * The browser's own scroll restoration, off for the entry the shopper leaves
+ * with a Back stash (`history.scrollRestoration = 'manual'`): a load of it
+ * (Back that is not a restore from memory: iOS Safari's) is placed by Luma
+ * after its render. The browser's restoration ran before it, on a page not
+ * grown to the stashed pages yet, and could land after Luma's place too.
+ * Only from `auto`: a host that set it (Turbo, a router) keeps its own.
+ * Back on (`releaseScroll`) once Luma has placed the page, or when the
+ * document moves on within itself (an SPA's navigation: theirs to restore).
+ */
+let ownScroll = false;
+/** Off for this entry, when it is the browser's (or already ours): 1, for the stash's `sr`. */
+export const holdScroll = (): 1 | undefined => {
+  try {
+    if (!ownScroll && history.scrollRestoration !== 'auto') return undefined;
+    history.scrollRestoration = 'manual';
+    ownScroll = true;
+    return 1;
+  } catch {
+    return undefined;
+  }
+};
+/** A page loaded on an entry Luma turned it off for (the stash's `sr`): Luma's to turn back on. */
+export const adoptScroll = () => void (ownScroll = true);
+/** Back to the browser's, if Luma turned it off. */
+export const releaseScroll = () => {
+  if (!ownScroll) return;
+  ownScroll = false;
+  try {
+    if (history.scrollRestoration === 'manual') history.scrollRestoration = 'auto';
+  } catch {}
+};
+
 /**
  * Keep what the shopper is looking at in place across a re-render (a
  * revalidated result): the first tile link in the viewport stays where it is.
  */
 export const keepViewport = (root: Element, f: () => void) => {
-  let pin: { href: string; top: number } | null = null;
-  for (const a of root.querySelectorAll<HTMLAnchorElement>('[data-lbx-list] a[href]')) {
-    const top = a.getBoundingClientRect().top;
-    if (top >= 0) {
-      pin = { href: a.href, top };
-      break;
-    }
-  }
+  const pin = scrollSpot(root);
   f();
-  if (!pin) return;
-  const a = linkTo(root, pin.href);
+  const a = pin.href ? linkTo(root, pin.href, pin.n) : null;
   if (a) {
-    const d = a.getBoundingClientRect().top - pin.top;
+    const d = a.getBoundingClientRect().top - (pin.top ?? 0);
     if (Math.abs(d) >= 1) scroll(scrollY + d);
   }
 };

package/src/widgets/listing/stash.ts

@@ -5,8 +5,12 @@
 //   (widgets/search/speculate.ts). Used by a plain navigation (or a prerender
 //   of the page) within its `ttl` (2 minutes), once.
 // - `back`: the listing as the shopper left it for a product page (pages
-//   1..N, where they were). Used by a back/forward load within 30 minutes; the
-//   listing then restores the scroll position and revalidates in the background.
+//   1..N, where they were). Used by a back/forward load within 30 minutes, or
+//   by a reload or a navigation from the page itself within a minute (a link
+//   whose server redirects back to it); the listing then restores the scroll
+//   position and revalidates in the background. Otherwise, on a load of the
+//   entry left (back/forward, reload): where they were only (`stale`), the
+//   browser's own restoration being off for it (`sr`).
 // Bounded: at most 3 entries (one `spec`), 400k characters each; a full store
 // drops ours first. Best-effort: storage may be unavailable, never required.
 
@@ -14,6 +18,7 @@ import { navigation, STASH, stashFits, stashKey } from '../../core/stash';
 import { pageKey } from '../../core/page';
 import type { ListingResult } from './query';
 import type { Query } from './state';
+import type { Spot } from './instant';
 
 export interface Stash {
   v: 1;
@@ -26,8 +31,12 @@ export interface Stash {
   route: string;
   query: Query;
   result: ListingResult;
-  /** back: the link the shopper followed (its href, its top in the viewport) and scrollY where it is gone. */
-  scroll?: { y: number; href?: string; top?: number };
+  /** back: the link the shopper followed (its href, which of the laid-out links to it, its top in the viewport) and scrollY where it is gone. */
+  scroll?: Spot;
+  /** back: Luma turned the browser's own scroll restoration off for the entry left (`history.scrollRestoration`): back on once restored. */
+  sr?: 1;
+  /** Read only: too old to render from, where the shopper was is all that is used. */
+  stale?: true;
 }
 
 const MAX_CHARS = 400_000;
@@ -48,7 +57,7 @@ const entries = (except?: string) => {
   return out.sort((a, b) => a.at - b.at);
 };
 
-/** The stashed result this page load may render from, or null. */
+/** The stashed result this page load may render from, or null. `stale`: a Back entry too old to render, for its scroll only. */
 export const readStash = (route: string, href: string): Stash | null => {
   try {
     const key = stashKey(href);
@@ -59,8 +68,22 @@ export const readStash = (route: string, href: string): Stash | null => {
     const nav = navigation();
     const fresh = s.v === 1 && age >= 0 && age < (s.ttl ?? MAX_AGE[s.kind] ?? 0);
     if (!fresh || s.kind === 'spec') sessionStorage.removeItem(key); // a speculation is used once
-    if (!fresh || s.route !== route || pageKey(nav.url) !== pageKey(href)) return null;
-    return stashFits(s.kind) ? s : null;
+    if (s.route !== route || pageKey(nav.url) !== pageKey(href)) return null;
+    if (fresh && stashFits(s.kind, s.at)) return s;
+    // The entry left loaded again (Back after long, a reload after the round
+    // trip's minute): the browser restores nothing where Luma turned its
+    // restoration off; where the shopper was is still known.
+    const again = nav.type === 'back_forward' || nav.type === 'reload';
+    return s.v === 1 && s.kind === 'back' && s.sr && again ? { ...s, stale: true } : null;
+  } catch {
+    return null;
+  }
+};
+
+/** This URL's stash as it is, whatever the load (the back/forward cache's restore: where the shopper was). */
+export const peekStash = (href: string): Stash | null => {
+  try {
+    return JSON.parse(sessionStorage.getItem(stashKey(href)) ?? 'null') as Stash | null;
   } catch {
     return null;
   }
@@ -76,7 +99,7 @@ export const dropStash = (href: string) => {
 /** false: too big, or storage refused it. */
 export const writeStash = (href: string, s: Omit<Stash, 'v' | 'at'>) => {
   try {
-    const json = JSON.stringify({ at: Date.now(), v: 1, kind: s.kind, ttl: s.ttl, route: s.route, query: s.query, result: s.result, scroll: s.scroll });
+    const json = JSON.stringify({ at: Date.now(), v: 1, kind: s.kind, ttl: s.ttl, route: s.route, query: s.query, result: s.result, scroll: s.scroll, sr: s.sr });
     if (json.length > MAX_CHARS) return false;
     const key = stashKey(href);
     const others = entries(key);