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/contexts/category/CategoriesProvider.tsx

@@ -22,7 +22,7 @@ import { deserializeCategory } from "../../utils/shared/deserialize.ts";
 import type { Wire } from "../../../shared/api.ts";
 import { expectOk } from "../../utils/shared/api.ts";
 
-/** How long a failed first fetch waits before it is tried again. */
+// A failed first fetch waits this long before it is tried again.
 const RETRY_MS = 10_000;
 
 /**

src/contexts/social/FollowContext.ts

@@ -28,7 +28,10 @@ export interface FollowContextValue {
   isLoaded: boolean;
 }
 
-/** Given to a consumer outside `FollowProvider`: nothing is followed. */
+/**
+ * Given to a consumer outside `FollowProvider`, for which nothing is
+ * followed.
+ */
 export const defaultFollowValue: FollowContextValue = {
   followedUserIds: new Set(),
   followedPlaylistIds: new Set(),

src/contexts/social/FollowProvider.tsx

@@ -23,7 +23,7 @@ export interface FollowProviderProps {
   children: ReactNode;
 }
 
-/** How long a failed fetch of the follows waits before it is tried again. */
+// A failed fetch of the follows waits this long before it is tried again.
 const RETRY_MS = 10_000;
 
 /**

src/contexts/theme/ThemeContext.ts

@@ -8,9 +8,9 @@
 import { createContext } from "react";
 
 /**
- * Every site style, which `ThemeProvider` checks a stored choice against. Each
- * has a stylesheet under `src/themes/`, keyed on the root element's
- * `data-style`, which is absent for "smooth".
+ * Lists every site style, which `ThemeProvider` checks a stored choice
+ * against. Each has a stylesheet under `src/themes/`, keyed on the root
+ * element's `data-style`, which is absent for "smooth".
  */
 export const STYLE_NAMES = [
   "smooth",
@@ -20,12 +20,12 @@ export const STYLE_NAMES = [
   "kanagawa",
   "melange",
 ] as const;
-/** One of {@link STYLE_NAMES}. */
+/** Held by `ThemeProvider` for the style chosen in this browser. */
 export type StyleName = typeof STYLE_NAMES[number];
 
-/** Every color scheme; "auto" follows the system's. */
+/** Lists every color scheme. "auto" follows the system's. */
 export const COLOR_SCHEMES = ["auto", "light", "dark"] as const;
-/** One of {@link COLOR_SCHEMES}. */
+/** Held by `ThemeProvider` for the color scheme chosen in this browser. */
 export type ColorScheme = typeof COLOR_SCHEMES[number];
 
 /**

src/contexts/ws/WSContext.ts

@@ -140,14 +140,14 @@ export interface WSContextValue {
    */
   recentDumps: Dump[];
   /**
-   * Dumps deleted this session, or made private by someone else, for the
-   * lists to filter out. A dump made public again leaves it.
+   * It holds the dumps deleted this session, or made private by someone else,
+   * for the lists to filter out. A dump made public again leaves it.
    */
   deletedDumpIds: Set<string>;
   lastVoteEvent: VoteEvent | null;
   /**
-   * The dump as its latest `dump_created` or `dump_updated` has it, for the
-   * lists to update it in place, or put it back where it was.
+   * It holds the dump as its latest `dump_created` or `dump_updated` has it,
+   * for the lists to update it in place, or put it back where it was.
    */
   lastDumpEvent: Dump | null;
   lastPlaylistEvent: PlaylistEvent | null;

src/contexts/ws/WSProvider.tsx

@@ -93,13 +93,15 @@ const CHAT_READ_THROTTLE = 1_000;
  */
 const CHAT_ECHO_WINDOW = 60_000;
 
-/** Toggles of one item that the server hasn't acknowledged yet. */
+/**
+ * Held by {@link useOptimisticToggles} for an item whose toggles the server
+ * hasn't all acknowledged yet. `count` and `on` are as before the first of
+ * them, for a failure to restore.
+ */
 interface PendingToggle {
   timeout: ReturnType<typeof setTimeout>;
-  /** The count and state before the first of them, to restore on failure. */
   count: number;
   on: boolean;
-  /** How many acks are still to come. */
   outstanding: number;
 }
 
@@ -117,7 +119,7 @@ interface OptimisticToggles {
   /** Restores the item as it was before its toggles, now. */
   fail: (id: string) => void;
   /**
-   * Settles every toggle against the server's set after a (re)connect: each
+   * Settles every toggle against the server's set after a (re)connect. Each
    * count moves by one from its baseline when the server's state differs.
    */
   reconcile: (serverOn: Set<string>) => void;
@@ -265,7 +267,7 @@ export function WSProvider({ children }: WSProviderProps): React.JSX.Element {
   const [avatarOverrides, setAvatarOverrides] = useState<
     Record<string, AvatarOverride>
   >({});
-  // Never reset: pages compare it with the value they last saw.
+  // It is never reset, since pages compare it with the value they last saw.
   const [connectionEpoch, setConnectionEpoch] = useState(0);
   const [followsVersion, setFollowsVersion] = useState(0);