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/components/profile/DescriptionEditor.tsx

@@ -45,7 +45,8 @@ export function DescriptionEditor(
 
   const onSubmit = form.submit(async ({ description }) => {
     const trimmed = description.trim();
-    // Sent even when empty: left out, the server would keep the old one.
+    // Sent even when empty, since the server keeps the old one when it is left
+    // out.
     await expectOk<Wire<PublicUser>>(
       await authFetch(`${API_URL}/api/users/me`, {
         method: "PATCH",

src/components/profile/ProfileDumpsTab.tsx

@@ -1,5 +1,6 @@
 /**
- * The "dumps" tab of a profile: the user's dumps beside those they upvoted.
+ * Renders the "dumps" tab of a profile, which shows the user's dumps beside
+ * those they upvoted.
  *
  * @module
  */
@@ -18,7 +19,7 @@ export interface ProfileDumpsTabProps {
   dumps: PagedList<Dump>;
   votes: PagedList<Dump>;
   isOwnProfile: boolean;
-  /** From `useProfile`, which fades out a withdrawn upvote. */
+  /** It comes from `useProfile`, which fades out a withdrawn upvote. */
   upvotedCardClassName: (dump: Dump) => string | undefined;
 }
 

src/components/profile/ProfileFollowedTab.tsx

@@ -1,6 +1,6 @@
 /**
- * The "followed" tab of a profile: the users and the playlists the user
- * follows.
+ * Renders the "followed" tab of a profile, which shows the users and the
+ * playlists the user follows.
  *
  * @module
  */

src/components/profile/ProfileInviteesTab.tsx

@@ -1,6 +1,6 @@
 /**
- * The "invitees" tab of a profile: whom the user invited, and whom they
- * invited in turn.
+ * Renders the "invitees" tab of a profile, which shows whom the user invited,
+ * and whom they invited in turn.
  *
  * @module
  */

src/components/profile/ProfileManageTab.tsx

@@ -1,6 +1,6 @@
 /**
- * The "manage" tab of a profile, which holds tools for another user on their
- * profile and site-wide tools on one's own.
+ * Renders the "manage" tab of a profile, which holds tools for another user on
+ * their profile and site-wide tools on one's own.
  *
  * @module
  */

src/components/profile/ProfileOwnActions.tsx

@@ -1,6 +1,6 @@
 /**
- * Renders the actions of the signed-in user's own profile header: inviting
- * someone, and whatever the header adds, the log out button.
+ * Renders the actions of the signed-in user's own profile header, which invite
+ * someone, beside the log out button the header adds.
  *
  * @module
  */

src/components/profile/ProfilePlaylistsTab.tsx

@@ -1,5 +1,6 @@
 /**
- * The "playlists" tab of a profile: the playlists the user made.
+ * Renders the "playlists" tab of a profile, which shows the playlists the user
+ * made.
  *
  * @module
  */
@@ -17,7 +18,7 @@ export interface ProfilePlaylistsTabProps {
   username: string;
   playlists: PagedList<Playlist>;
   isOwnProfile: boolean;
-  /** From `useProfile`, to put a playlist made here first. */
+  /** It comes from `useProfile`, and puts a playlist made here first. */
   setPlaylists: (fn: (items: Playlist[]) => Playlist[]) => void;
 }
 

src/components/profile/ProfileSection.tsx

@@ -14,11 +14,11 @@ import { Trans } from "@lingui/react/macro";
  */
 export interface ProfileSectionProps {
   title: ReactNode;
-  /** Buttons at the end of the title row. */
+  /** They go at the end of the title row. */
   actions?: ReactNode;
   /**
-   * The page with the whole list, of which the section shows the first page.
-   * The profile leaves it out while the list is empty.
+   * It links to the page with the whole list, of which the section shows the
+   * first page. The profile leaves it out while the list is empty.
    */
   viewAllHref?: string;
   children: ReactNode;

src/components/profile/ProfileSettingsTab.tsx

@@ -1,6 +1,6 @@
 /**
- * The "settings" tab of the signed-in user's own profile: their password, and
- * this browser's preferences.
+ * Renders the "settings" tab of the signed-in user's own profile, where they
+ * change their password and this browser's preferences.
  *
  * @module
  */

src/components/profile/SettingRow.tsx

@@ -11,7 +11,7 @@ import type { ReactNode } from "react";
  */
 export interface SettingRowProps {
   label: ReactNode;
-  /** The control, usually a `Segmented`. */
+  /** It is the row's control, usually a `Segmented`. */
   children: ReactNode;
 }