cursedbelt 5.22.0 → 5.23.0

package/src/react/hooks/useScrollMemory.spec.tsx

@@ -224,4 +224,42 @@ describe('useScrollMemory', () => {
     render(<Shell at='/' el={s.el} />);
     expect(s.el.scrollTop).toBe(12_000);
   });
+
+  test('a scroller that mounts AFTER the hook — a list behind a loading spinner — is still remembered', () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(8_000);
+    const list = { state: window.history.state, path: '/' };
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+
+    back(list);
+    const Late = ({ ready }: { ready: boolean }) => {
+      useScrollMemory('/', { scroller: () => (ready ? s.el : null) });
+      return null;
+    };
+    cleanup();
+    const late = render(<Late ready={false} />);
+    late.rerender(<Late ready />);
+    expect(s.el.scrollTop).toBe(8_000);
+  });
+
+  test('a list screen that owns its scroller files on unmount and restores on remount', () => {
+    const s = fakeScroller(20_000);
+    const List = () => {
+      useScrollMemory('/people', { scroller: () => s.el });
+      return null;
+    };
+    window.history.replaceState(null, '', '/people');
+    const first = render(<List />);
+    s.scrollTo(5_500);
+    const list = { state: window.history.state, path: '/people' };
+    push('/person/1'); // the app navigates; the list unmounts
+    first.unmount();
+    s.el.scrollTop = 0; // a new screen's scroller, as far as this list knows
+
+    back(list);
+    render(<List />);
+    expect(s.el.scrollTop).toBe(5_500);
+  });
 });

package/src/react/hooks/useScrollMemory.ts

@@ -31,67 +31,102 @@ import { type RefObject, useLayoutEffect, useRef } from 'react';
  * - **A replaced URL is the same place**: when the location changes but the history entry does
  *   not (a filter written with `replaceState`), the scroll is left alone.
  *
- * Mount it ONCE per scroller, above the screens that swap — the app shell, keyed on the route.
+ * Mount it ONCE per scroller: in the app shell keyed on the route when the screens swap under one
+ * scroller (the window, a shell `ScrollArea`), or in the list screen itself when each screen owns
+ * its own `ScrollArea` — mounting is then the arrival and unmounting the leave.
  */
 export function useScrollMemory(location: string, options: ScrollMemoryOptions = {}): void {
   const { enabled = true, deadlineMs = RESTORE_DEADLINE_MS } = options;
-  // The scroller is read through a ref so an inline `() => el` does not re-run the effect
-  // every render — which would file and restore on every keystroke.
-  const scrollerRef = useRef(options.scroller);
-  scrollerRef.current = options.scroller;
+  const spec = options.scroller ?? 'window';
   const last = useRef<{ id: string; location: string } | null>(null);
+  const session = useRef<Session | null>(null);
 
+  // 🔴 Checked EVERY commit, not on a dependency list: the scroller can mount after the hook — a
+  // list behind a loading spinner has no ScrollArea on its first render — and an effect keyed on
+  // the location alone would find nothing, return, and never look again, so that whole visit
+  // would go unremembered. A session ends and the next begins only when the place, the switch or
+  // the scroller ELEMENT actually changes; every other commit is one comparison.
   useLayoutEffect(() => {
-    if (!enabled) return;
-    const scroller = resolveScroller(scrollerRef.current ?? 'window');
-    if (!scroller) return;
-    if (scroller.isWindow && 'scrollRestoration' in window.history) {
-      // Left on `auto`, the browser restores at `popstate` — into the screen being LEFT, before
-      // React has swapped it — and the restore below would have to fight it.
-      window.history.scrollRestoration = 'manual';
-    }
-    const id = entryId();
-    if (!id) return;
-
-    // Same entry, different location: the URL was replaced in place. It is the same place.
-    const replacedInPlace = last.current?.id === id && last.current.location !== location;
-    last.current = { id, location };
-
-    // What gets filed when this entry is left. While a restore is pending it is the TARGET, not
-    // the partial offset on screen — leaving mid-restore (or StrictMode's rehearsal unmount) must
-    // not overwrite a deep position with a shallow one.
-    let offset = scroller.get();
-    let cancelRestore: (() => void) | null = null;
-
-    if (!replacedInPlace) {
-      const target = recalled(id);
-      if (target > 0) {
-        offset = target;
-        cancelRestore = restore(scroller, target, deadlineMs, (outcome) => {
-          cancelRestore = null;
-          if (outcome !== 'reached') offset = scroller.get();
-        });
-      } else {
-        scroller.set(0);
-        offset = 0;
-      }
+    const scroller = enabled ? resolveScroller(spec) : null;
+    const current = session.current;
+    if (current && scroller && current.location === location && current.target === scroller.events) return;
+    if (!current && !scroller) return;
+    current?.end();
+    session.current = scroller ? begin(scroller, location, last, deadlineMs) : null;
+  });
+  useLayoutEffect(
+    () => () => {
+      session.current?.end();
+      session.current = null;
+    },
+    [],
+  );
+}
+
+interface Session {
+  location: string;
+  target: EventTarget;
+  /** Stop tracking and file the offset under this entry. */
+  end(): void;
+}
+
+/** Arrive on the current history entry with this scroller: restore or start at the top, then track. */
+function begin(
+  scroller: Scroller,
+  location: string,
+  last: { current: { id: string; location: string } | null },
+  deadlineMs: number,
+): Session | null {
+  if (scroller.isWindow && 'scrollRestoration' in window.history) {
+    // Left on `auto`, the browser restores at `popstate` — into the screen being LEFT, before
+    // React has swapped it — and the restore below would have to fight it.
+    window.history.scrollRestoration = 'manual';
+  }
+  const id = entryId();
+  if (!id) return null;
+
+  // Same entry, different location: the URL was replaced in place. It is the same place.
+  const replacedInPlace = last.current?.id === id && last.current.location !== location;
+  last.current = { id, location };
+
+  // What gets filed when this entry is left. While a restore is pending it is the TARGET, not
+  // the partial offset on screen — leaving mid-restore (or StrictMode's rehearsal unmount) must
+  // not overwrite a deep position with a shallow one.
+  let offset = scroller.get();
+  let cancelRestore: (() => void) | null = null;
+
+  if (!replacedInPlace) {
+    const target = recalled(id);
+    if (target > 0) {
+      offset = target;
+      cancelRestore = restore(scroller, target, deadlineMs, (outcome) => {
+        cancelRestore = null;
+        if (outcome !== 'reached') offset = scroller.get();
+      });
+    } else {
+      scroller.set(0);
+      offset = 0;
     }
+  }
 
-    const onScroll = () => {
-      if (!cancelRestore) offset = scroller.get();
-    };
-    const onHide = () => file(id, offset);
-    scroller.events.addEventListener('scroll', onScroll, { passive: true });
-    window.addEventListener('pagehide', onHide);
-    return () => {
+  const onScroll = () => {
+    if (!cancelRestore) offset = scroller.get();
+  };
+  const onHide = () => file(id, offset);
+  scroller.events.addEventListener('scroll', onScroll, { passive: true });
+  window.addEventListener('pagehide', onHide);
+  return {
+    location,
+    target: scroller.events,
+    end() {
       const pending = cancelRestore;
       cancelRestore = null;
       pending?.();
       scroller.events.removeEventListener('scroll', onScroll);
       window.removeEventListener('pagehide', onHide);
       file(id, offset);
-    };
-  }, [location, enabled, deadlineMs]);
+    },
+  };
 }
 
 /** What scrolls: the window, or an element — by ref or by a getter read when the screen arrives. */

package/src/react/media/DenseGalleryShell.tsx

@@ -5,6 +5,7 @@ import {
   type CSSProperties,
   type MouseEvent as ReactMouseEvent,
   type ReactNode,
+  type Ref,
   useCallback,
   useEffect,
   useState,
@@ -231,6 +232,12 @@ export interface DenseGalleryShellProps<O extends string = string> {
    * exactly one place the caption height is written down.
    */
   rowExtraHeight?: number;
+  /**
+   * The shell's root element (`.cbgd-root`) — for a caller that has to find the browse view's
+   * scroller in the DOM. `MediaGallery` uses it to put the grid back where you were when a
+   * file closes (`media-gallery/galleryReturn.ts`), because closing a file mounts a new shell.
+   */
+  rootRef?: Ref<HTMLDivElement>;
 }
 
 /** The browse view: header + optional filter strip + a virtualized thumbnail grid. */
@@ -254,9 +261,10 @@ export function DenseGalleryShell<O extends string = string>({
   minColumnWidth = 160,
   // 🔴 Deliberately NOT defaulted here — see the prop's doc comment.
   rowExtraHeight,
+  rootRef,
 }: DenseGalleryShellProps<O>) {
   return (
-    <div className='cbgd-root'>
+    <div className='cbgd-root' ref={rootRef}>
       {chrome === 'none' ? null : (
         <header className='cbgd-header'>
           <span className='cbgd-title'>{title}</span>

package/src/react/media-gallery/GalleryTable.tsx

@@ -496,6 +496,8 @@ function GalleryTableRow({
       // The same two hooks the grid tile carries: the attribute is what the gallery's reveal
       // scrolls to, and `aria-current` is what says "this is the one" to a screen reader.
       data-playing={stageMark ? 'true' : undefined}
+      // How a returning table finds the last file shown — see `galleryReturn.ts`.
+      data-item-id={item.id}
       aria-current={stageMark ? 'true' : undefined}
       {...(previewSrc
         ? {

package/src/react/media-gallery/MediaGallery.tsx

@@ -78,6 +78,7 @@ import {
 } from '../hooks/useCheckboxSelection.js';
 import { DenseGalleryDetail, DenseGalleryShell } from '../media/DenseGalleryShell.js';
 import { CBGD_BARE_TILE_HEIGHT } from '../media/VirtualMediaGrid.js';
+import { useGalleryReturn } from './galleryReturn.js';
 import { useHlsSource } from '../media/hlsSource.js';
 import {
   isRecoverableFault,
@@ -552,12 +553,16 @@ interface TileDrag {
  * `stopPropagation` in {@link SelectBox} buys.
  */
 function TileShell({
+  id,
   name,
   selection,
   drag,
   stageMark,
   children,
 }: {
+  /** The item's id, carried as `data-item-id` — how a returning grid finds the last file shown
+   *  (`galleryReturn.ts`). */
+  id: string;
   name: string;
   selection?: TileSelection;
   drag?: TileDrag;
@@ -582,6 +587,7 @@ function TileShell({
       // The hook the reveal below finds the tile by — see `MediaGallery`'s `revealPlaying`.
       // An attribute rather than the class, so the query cannot be broken by a styling change.
       data-playing={stageMark ? 'true' : undefined}
+      data-item-id={id}
       aria-current={stageMark ? 'true' : undefined}
       // 🔴 The DRAGGABLE element is this wrapper, not the tile inside it. Every tile branch
       // is a <button>, and a draggable button is a browser-by-browser coin toss: some start
@@ -684,7 +690,7 @@ function GalleryTile({
    * handlers, so this costs nothing and cannot change behavior anywhere else.
    */
   return (
-    <TileShell name={item.name} selection={selection} drag={drag} stageMark={stageMark}>
+    <TileShell id={item.id} name={item.name} selection={selection} drag={drag} stageMark={stageMark}>
       <RawGalleryTile
         item={item}
         cache={cache}
@@ -2021,6 +2027,17 @@ export function MediaGallery({
   }, [checkedKey]);
 
   const selected = selectedId ? (items.find((i) => i.id === selectedId) ?? null) : null;
+  /** The browse view's root — how the return below finds the grid it puts back in place. */
+  const browseRootRef = useRef<HTMLDivElement | null>(null);
+  // Closing a file mounts a NEW grid; this puts it back where you were, then shows the last
+  // file the stage showed. Task 2255 — see `galleryReturn.ts`.
+  useGalleryReturn({
+    rootRef: browseRootRef,
+    browsing: selected === null,
+    viewMode,
+    shownId: selected?.id ?? null,
+    displayIds,
+  });
   const select = (item: MediaGalleryItem | null) => {
     // Only move our own state when we own it; a controlled consumer decides for itself what
     // the notification means.
@@ -3164,6 +3181,7 @@ export function MediaGallery({
     {capabilityDialogs}
     <DenseGalleryShell<MediaGalleryOrder>
       {...(tileCaptions ? {} : { rowExtraHeight: CBGD_BARE_TILE_HEIGHT })}
+      rootRef={browseRootRef}
       title={title}
       order={{
         value: order,

package/src/react/media-gallery/galleryReturn.ts

@@ -0,0 +1,248 @@
+/**
+ * Closing a file puts the grid back where you were — task 2255.
+ *
+ * Owner, 2026-09-28, after flix's "Back keeps your place": *"is a common enough need … I want it
+ * to be in cb … find other apps we have that have scrolling and similar issues where we can't
+ * go back to the right place like flix had"*.
+ *
+ * `MediaGallery` draws `DenseGalleryDetail` while a file is open and `DenseGalleryShell`
+ * otherwise. They are different trees, so closing a file — by ✕, by a deep link's Back
+ * (`useGalleryDeepLink`'s `?i=`), by deleting it — MOUNTS A NEW GRID, and its scroller starts
+ * at zero. Measured in Chromium before this (`e2e/gallery-return.spec.ts`, 240 tiles, scrolled
+ * to 3,000px): every close landed at scrollTop 0, at phone and desktop size, two hundred tiles
+ * from where you had been.
+ *
+ * 🔴 Why not `useScrollMemory`. That hook is per HISTORY ENTRY, and a gallery's open/close is
+ * a history entry only when its consumer deep-links it. An uncontrolled gallery closes with no
+ * navigation at all, so the memory has to live with the gallery — which is also what keeps
+ * every consumer from having to wire anything.
+ *
+ * Two rules, in order:
+ * 1. **The offset comes back** — the browse scroller's own `scrollTop` (the tile grid's
+ *    `.cbgd-grid`, or the table's `.cbgt-root`), recorded while you browse and put back when
+ *    the view returns, if it returns in the same grid/table mode. It retries each frame while
+ *    the virtualized track is still growing into the offset, and a touch, wheel, key or
+ *    pointer press cancels it — the viewer always wins.
+ * 2. **…then the last file SHOWN is on screen.** Stepping through twenty files moves you: the
+ *    place you are now is the last file the stage showed, not the one you opened. When that
+ *    file's tile is not visible after rule 1 it is brought to the middle of the scroller. A
+ *    tile that is already even partly visible is left alone — a grid that jumps a few pixels
+ *    under a tile you can see reads as a bug (the same limit the strip's reveal keeps).
+ *    A virtualized tile that is not mounted is found by arithmetic on the tiles that are:
+ *    their row pitch and column count place it, and the next frame centres it exactly.
+ */
+import { type RefObject, useEffect, useLayoutEffect, useRef } from 'react';
+
+/** The browse view's scroller in either view: the tile grid, or the table's frame. */
+const SCROLLER = '.cbgd-grid, .cbgt-root';
+/** Every tile and every table row carries its item's id under this attribute. */
+export const ITEM_ID_ATTR = 'data-item-id';
+/** How long a return may keep trying before it settles for what the scroller can hold. */
+const DEADLINE_MS = 1500;
+const CANCEL_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'] as const;
+
+export interface GalleryReturnOptions {
+  /** `.cbgd-root` of the browse view — `DenseGalleryShell`'s `rootRef`. */
+  rootRef: RefObject<HTMLDivElement | null>;
+  /** True while the browse view (no file open) is the one on screen. */
+  browsing: boolean;
+  /** Grid or table: an offset recorded in one means nothing in the other. */
+  viewMode: string;
+  /** The file on the stage right now, or null. */
+  shownId: string | null;
+  /** The displayed order, which is what places a tile that is not mounted. */
+  displayIds: readonly string[];
+}
+
+export function useGalleryReturn({
+  rootRef,
+  browsing,
+  viewMode,
+  shownId,
+  displayIds,
+}: GalleryReturnOptions): void {
+  const saved = useRef<{ mode: string; top: number } | null>(null);
+  const lastShown = useRef<string | null>(null);
+  const restoring = useRef(false);
+  const wasBrowsing = useRef(browsing);
+  // Read through refs at fire time: they are inputs the return needs CURRENT, not triggers.
+  const modeRef = useRef(viewMode);
+  const idsRef = useRef(displayIds);
+  modeRef.current = viewMode;
+  idsRef.current = displayIds;
+  if (shownId) lastShown.current = shownId;
+
+  // Record the browse scroller's offset while browsing. Capture phase, because `scroll` does
+  // not bubble and the scroller is whichever of the two views is mounted.
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!browsing || !root) return;
+    const onScroll = (event: Event): void => {
+      const target = event.target;
+      if (restoring.current || !(target instanceof HTMLElement) || !target.matches(SCROLLER)) return;
+      saved.current = { mode: modeRef.current, top: target.scrollTop };
+    };
+    root.addEventListener('scroll', onScroll, { capture: true, passive: true });
+    return () => root.removeEventListener('scroll', onScroll, { capture: true });
+  }, [browsing, rootRef]);
+
+  // A layout effect, so the offset is back before the returning grid is ever painted at zero.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `browsing` is the one trigger — a return is the moment it turns true. Everything else is read through refs above, on purpose: a re-sort or a new page of items must not replay a return.
+  useLayoutEffect(() => {
+    const returning = browsing && !wasBrowsing.current;
+    wasBrowsing.current = browsing;
+    if (!returning) return;
+    const scroller = rootRef.current?.querySelector<HTMLElement>(SCROLLER);
+    if (!scroller) return;
+    const target = saved.current?.mode === modeRef.current ? saved.current.top : null;
+    const revealId = lastShown.current;
+    if (target === null && !revealId) return;
+    return returnTo(scroller, target, revealId, idsRef, () => {
+      restoring.current = false;
+      saved.current = { mode: modeRef.current, top: scroller.scrollTop };
+    }, restoring);
+  }, [browsing]);
+}
+
+/**
+ * Put `scroller` back at `target`, then bring `revealId`'s tile into view. Returns the cancel.
+ */
+function returnTo(
+  scroller: HTMLElement,
+  target: number | null,
+  revealId: string | null,
+  idsRef: RefObject<readonly string[]>,
+  done: () => void,
+  restoring: { current: boolean },
+): () => void {
+  // Each phase gets its own deadline, so a list that never grows back into the offset still
+  // leaves the reveal its full budget.
+  let started = performance.now();
+  let frame = 0;
+  let phase: 'offset' | 'reveal' | 'centre' = target === null ? 'reveal' : 'offset';
+  let finished = false;
+  restoring.current = true;
+
+  const finish = (): void => {
+    if (finished) return;
+    finished = true;
+    cancelAnimationFrame(frame);
+    for (const type of CANCEL_EVENTS) scroller.removeEventListener(type, finish);
+    done();
+  };
+  for (const type of CANCEL_EVENTS) scroller.addEventListener(type, finish, { passive: true });
+
+  const tick = (): void => {
+    if (finished) return;
+    const late = performance.now() - started > DEADLINE_MS;
+    if (phase === 'offset' && target !== null) {
+      scroller.scrollTop = target;
+      // Reached, or the list is simply shorter now (a filter, a delete): settle for its end.
+      if (Math.abs(scroller.scrollTop - target) < 1 || late) {
+        phase = 'reveal';
+        started = performance.now();
+      }
+      frame = requestAnimationFrame(tick);
+      return;
+    }
+    const ids = idsRef.current ?? [];
+    const index = revealId ? ids.indexOf(revealId) : -1;
+    if (index < 0 || late) {
+      finish();
+      return;
+    }
+    const tile = scroller.querySelector<HTMLElement>(`[${ITEM_ID_ATTR}="${cssEscape(revealId ?? '')}"]`);
+    const band = visibleBand(scroller);
+    if (tile) {
+      const box = tile.getBoundingClientRect();
+      const visible = box.bottom > band.top && box.top < band.bottom;
+      // Rule 2's limit: a tile you can already see is not moved — unless WE just jumped to an
+      // estimate of it, which is only ever close.
+      if (!visible || phase === 'centre') scroller.scrollTop += centreDelta(box, band);
+      finish();
+      return;
+    }
+    // 🔴 Not mounted — but first make sure the VIRTUALIZER has caught up with the offset just
+    // set. The table re-windows on its own scroll state a render later, so for a frame or two
+    // after a jump it still holds the rows from the top; estimating off those would place a
+    // tile that is about to appear right where you are. Nothing mounted in the band = wait.
+    if (!mountedInBand(scroller, band)) {
+      frame = requestAnimationFrame(tick);
+      return;
+    }
+    // Truly windowed out. Place it by the tiles that ARE mounted.
+    const estimate = estimateTop(scroller, band, ids, index);
+    if (estimate === null) {
+      finish();
+      return;
+    }
+    scroller.scrollTop = estimate;
+    phase = 'centre';
+    frame = requestAnimationFrame(tick);
+  };
+
+  tick();
+  return () => {
+    if (finished) return;
+    finished = true;
+    cancelAnimationFrame(frame);
+    for (const type of CANCEL_EVENTS) scroller.removeEventListener(type, finish);
+    restoring.current = false;
+  };
+}
+
+interface Band {
+  top: number;
+  bottom: number;
+}
+
+/** The part of the scroller a person can see — below the table's sticky header, if any. */
+function visibleBand(scroller: HTMLElement): Band {
+  const view = scroller.getBoundingClientRect();
+  const head = scroller.querySelector('thead');
+  const top = head ? Math.max(view.top, head.getBoundingClientRect().bottom) : view.top;
+  return { top, bottom: view.bottom };
+}
+
+/** Does any tile or row sit in the visible band — i.e. has the window caught up? */
+function mountedInBand(scroller: HTMLElement, band: Band): boolean {
+  for (const el of scroller.querySelectorAll<HTMLElement>(`[${ITEM_ID_ATTR}]`)) {
+    const box = el.getBoundingClientRect();
+    if (box.bottom > band.top && box.top < band.bottom) return true;
+  }
+  return false;
+}
+
+function centreDelta(box: DOMRect, band: Band): number {
+  return box.top + box.height / 2 - (band.top + band.bottom) / 2;
+}
+
+/**
+ * A `scrollTop` that centres the tile at `index`, derived from the mounted ones: the first
+ * mounted row gives the column count (only the LAST row of a grid can be short), and the next
+ * row down gives the pitch. A table is the same arithmetic with one column.
+ */
+function estimateTop(scroller: HTMLElement, band: Band, ids: readonly string[], index: number): number | null {
+  const placed: { index: number; top: number; height: number }[] = [];
+  for (const el of scroller.querySelectorAll<HTMLElement>(`[${ITEM_ID_ATTR}]`)) {
+    const at = ids.indexOf(el.getAttribute(ITEM_ID_ATTR) ?? '');
+    if (at < 0) continue;
+    const box = el.getBoundingClientRect();
+    placed.push({ index: at, top: box.top - band.top + scroller.scrollTop, height: box.height });
+  }
+  if (placed.length === 0) return null;
+  placed.sort((a, b) => a.index - b.index);
+  const anchor = placed[0] as (typeof placed)[number];
+  const cols = Math.max(1, placed.filter((p) => Math.abs(p.top - anchor.top) < 1).length);
+  const below = placed.find((p) => p.top - anchor.top >= 1);
+  const rowOf = (at: number): number => Math.floor(at / cols);
+  const pitch = below ? (below.top - anchor.top) / (rowOf(below.index) - rowOf(anchor.index) || 1) : anchor.height;
+  const rows = rowOf(index) - rowOf(anchor.index);
+  const top = anchor.top + rows * pitch;
+  return Math.max(0, top + anchor.height / 2 - (band.bottom - band.top) / 2);
+}
+
+/** `CSS.escape` where it exists (every browser); ids are app-chosen strings. */
+function cssEscape(value: string): string {
+  return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : value.replace(/["\\]/g, '\\$&');
+}