v3: every paged list loads its pages one way, PlaylistDetail is split like the profile, and the comments keep the README's rules — Index, FollowedFeed, useUserDumpFeed, UserPlaylists, UserListPopover, Notifications, Search and the profile's followed users each hand-wrote "fetch the next page, append it, clear loadingMore on failure". A list the API pages is now a PagedList whose next page useLoadMore appends, and a list that loads on its own goes through usePagedList, which is useFetchState (now taking an initial value, as a restored cache, that starts loaded) plus useLoadMore. Pages are read by pageUrl with readPage (a refusal throws) or readFirstPage (a refusal is empty, as fetchFirstPage was), signed-in reads go through authFetch, and useFeedCache's saveState takes the list. Notifications keeps the socket's arrivals as their own list merged at render, as Index does with recentDumps, and marks them read in one effect. PlaylistDetail (963 lines) only puts the pieces together (146): usePlaylist holds the playlist, its live sync and its edits, PlaylistHeader, PlaylistEditForm and PlaylistDumpList are one file each, and LiveDumpCard is the vote wiring DumpCardList and the playlist both use. What it re-invented is shared: the load is useFetchState, a dump going private and back is usePositionAwareSync, deletes and edits are useDumpListSync (which also keeps comment counts, which the page didn't). A removal is sent when its fade ends, or as the page is left, so an undo sends nothing: the removal/re-add/reorder dance, the pending-undo order and the 80 ms debounce of its echoes are gone. A refused reorder goes back to the server's last order and says so, instead of reloading the page. The comments written since the documentation pass broke its rules in places: module docs as a label and a colon ("The "dumps" tab of a profile: …"), noun-phrase fragments on types, fields and constants, stale lists of callers, over-long lines; they are sentences now, and the ones the refactor made wrong (PlaylistDetail as useFading's and FollowPlaylistButton's caller, "the profiles" as usePositionAwareSync's only users) say what is true. 650 frontend and 214 backend tests pass (new: usePagedList, useFetchState's initial, pageUrl/readPage, the deferred removal, a dump returning at its place in a playlist), and tsc, eslint, doc:lint, deno check, deno lint and deno fmt are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/utils/feed/pagedList.ts

@@ -1,22 +1,24 @@
 /**
- * A list of which the first pages are loaded, as the pages holding several
- * such lists keep each one.
+ * Declares a list the API serves a page at a time, and reads its pages. Every
+ * such list in the app is a {@link PagedList}, whose next page `useLoadMore`
+ * appends.
  *
  * @module
  */
 
 import { DEFAULT_PAGE_SIZE } from "../../config/api.ts";
 import type { PaginatedData, Wire } from "../../../shared/api.ts";
-import { dataOr } from "../shared/api.ts";
+import { dataOr, expectOk } from "../shared/api.ts";
 
 /**
- * Held for each of its lists by `UserPlaylists` and the profile, whose lists
- * load together with the user and then a page at a time.
+ * Held for a list by `usePagedList`, or by a page that loads several lists
+ * with their user, as `UserPlaylists` and the profile do. `useLoadMore` loads
+ * the pages after `page`.
  */
 export interface PagedList<T> {
   items: T[];
   hasMore: boolean;
-  /** The last page loaded, from which loading more carries on. */
+  /** Loading more carries on from this page, the last loaded. */
   page: number;
   loadingMore: boolean;
 }
@@ -33,23 +35,63 @@ export function restoredList<T>(
   return { items, hasMore, page, loadingMore: false };
 }
 
+/**
+ * Checks whether `list` has a next page to load now, which `useLoadMore`
+ * requires and `useInfiniteScroll` takes as `enabled`. A list not loaded yet
+ * is null.
+ */
+export function canLoadMore(list: PagedList<unknown> | null): boolean {
+  return !!list && list.hasMore && !list.loadingMore;
+}
+
+/**
+ * Returns a setter of a list's items as a setter of the list, for the sync
+ * hooks, which edit items only.
+ */
+export function mapItems<T>(
+  fn: (items: T[]) => T[],
+): (list: PagedList<T>) => PagedList<T> {
+  return (list) => ({ ...list, items: fn(list.items) });
+}
+
+/** Returns `url` asking for page `page`, `limit` items long. */
+export function pageUrl(
+  url: string,
+  page: number,
+  limit = DEFAULT_PAGE_SIZE,
+): string {
+  return `${url}${url.includes("?") ? "&" : "?"}page=${page}&limit=${limit}`;
+}
+
+/**
+ * Returns the page `res` answers, its items deserialized.
+ *
+ * @throws {Error} With the server's message when it refuses, and when the
+ * body isn't an envelope.
+ */
+export async function readPage<T>(
+  res: Response,
+  deserialize: (wire: Wire<T>) => T,
+): Promise<PaginatedData<T>> {
+  const { items, hasMore } = await expectOk<PaginatedData<Wire<T>>>(res);
+  return { items: items.map(deserialize), hasMore };
+}
+
 const EMPTY_PAGE: PaginatedData<never> = { items: [], hasMore: false };
 
 /**
- * Returns the first page of the list at `url`, which takes `page` and `limit`
- * in its query, or an empty list when the server refuses it. The profile pages
- * load their lists with it beside the user, whose failure alone fails the
- * page.
+ * Returns the first page `res` answers as a list, or an empty list when the
+ * server refuses it. The profile pages read their lists with it beside the
+ * user, whose failure alone fails the page.
  *
- * @throws {Error} Offline, when aborted, and when the body isn't an envelope.
+ * @throws {Error} When the body isn't an envelope.
  */
-export async function fetchFirstPage<T>(
-  url: string,
+export async function readFirstPage<T>(
+  res: Response,
   deserialize: (wire: Wire<T>) => T,
-  init?: RequestInit,
 ): Promise<PagedList<T>> {
   const { items, hasMore } = await dataOr<PaginatedData<Wire<T>>>(
-    await fetch(`${url}?page=1&limit=${DEFAULT_PAGE_SIZE}`, init),
+    res,
     EMPTY_PAGE,
   );
   return firstPage(items.map(deserialize), hasMore);