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>

shared/api.ts

@@ -7,9 +7,9 @@
  */
 
 /**
- * The codes an {@link APIError} may carry, one per HTTP status, which the
- * backend's `APIException` derives from the status it is given. The frontend
- * shows the message and doesn't read the code.
+ * Lists the codes an {@link APIError} carries, one per HTTP status. The
+ * backend's `APIException` derives its code from the status it is given, and
+ * the frontend shows the message without reading the code.
  */
 export const APIErrorCode = {
   BAD_REQUEST: "BAD_REQUEST",

shared/validation.ts

@@ -29,8 +29,8 @@ export const VALIDATION = {
 } as const;
 
 /**
- * Matches a valid username: letters, digits and underscores, within the
- * `VALIDATION` limits. Sign-up checks it on both sides; it is the same `\w`
+ * Matches a valid username, made of letters, digits and underscores within the
+ * `VALIDATION` limits. Sign-up checks it on both sides. It uses the same `\w`
  * that a mention's pattern reads a name with.
  */
 export const USERNAME_RE: RegExp = new RegExp(

shared/ws.ts

@@ -249,10 +249,10 @@ export interface CommentLikeAckMessage {
 }
 
 /**
- * Sent by the server when a dump is posted: to every socket if it is public,
- * to its poster's alone if private. Also sent to everyone but the poster when
- * a private dump goes public, since to them it is new. `WSProvider` puts it at
- * the top of its recent dumps.
+ * Sent by the server when a dump is posted, to every socket if it is public
+ * and to its poster's alone if it is private. It also goes to everyone but the
+ * poster when a private dump goes public, since to them it is new.
+ * `WSProvider` puts it at the top of its recent dumps.
  */
 export interface DumpCreatedMessage {
   type: "dump_created";
@@ -260,8 +260,8 @@ export interface DumpCreatedMessage {
 }
 
 /**
- * Sent by the server when a dump changes: to every socket if it is public, to
- * its poster's alone if private, as when it has just gone private.
+ * Sent by the server when a dump changes, to every socket if it is public and
+ * to its poster's alone if it is private, as when it has just gone private.
  * `WSProvider` refreshes it in place, without moving it up the feeds.
  */
 export interface DumpUpdatedMessage {
@@ -270,9 +270,9 @@ export interface DumpUpdatedMessage {
 }
 
 /**
- * Sent by the server when a dump is deleted: to every socket if it was
- * public, to its poster's alone if private. Also sent to everyone but the
- * poster when a public dump goes private. `WSProvider` drops it from every
+ * Sent by the server when a dump is deleted, to every socket if it was public
+ * and to its poster's alone if it was private. It also goes to everyone but
+ * the poster when a public dump goes private. `WSProvider` drops it from every
  * list.
  */
 export interface DumpDeletedMessage {