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>

api/config.ts

@@ -55,10 +55,10 @@ export const PUBLIC_URL: string =
   Deno.env.get("GERBEUR_PUBLIC_URL")?.trim().replace(/\/$/, "") ||
   `http://localhost:${PORT}`;
 /**
- * The URL the frontend is served from (`GERBEUR_FRONTEND_URL`), when it isn't
- * {@link PUBLIC_URL}, as with a separate Vite server, without a trailing slash.
- * It is an allowed origin, and password reset links and the Open Graph tags'
- * page URLs point to it.
+ * Holds the URL the frontend is served from (`GERBEUR_FRONTEND_URL`), without
+ * a trailing slash, when it isn't {@link PUBLIC_URL}, as with a separate Vite
+ * server. It is an allowed origin, and password reset links and the Open Graph
+ * tags' page URLs point to it.
  */
 export const FRONTEND_URL: string =
   Deno.env.get("GERBEUR_FRONTEND_URL")?.trim().replace(/\/$/, "") ||
@@ -95,7 +95,7 @@ export const ATTACHMENTS_DIR = `${UPLOADS_DIR}/attachments`;
 export const THUMBNAILS_DIR = `${UPLOADS_DIR}/thumbnails`;
 
 /**
- * The largest image upload accepted, in bytes, for avatars, covers, thumbnails
+ * Caps the size of an image upload, in bytes, for avatars, covers, thumbnails
  * and attachments. lib/upload.ts states it in megabytes in its error.
  */
 export const MAX_IMAGE_SIZE_BYTES = 5 * 1024 * 1024;

api/db/connection.ts

@@ -15,8 +15,8 @@ import { runStartupTasks } from "./startup.ts";
 const isNew = await Deno.stat(DB_PATH).then(() => false, () => true);
 
 /**
- * The server's only connection. Its queries are synchronous, so each one
- * blocks the event loop while it runs.
+ * Serves every query of the server, as its only connection. Its queries are
+ * synchronous, so each one blocks the event loop while it runs.
  */
 export const db: DatabaseSync = new DatabaseSync(DB_PATH);
 // schema.sql holds every migration's change, so on a new database each

api/db/migrate.ts

@@ -32,10 +32,10 @@ interface Migration {
 }
 
 /**
- * Every migration, in the order they run. A new one goes at the end, along
- * with the same change to schema.sql, and a shipped one is never edited or
- * moved. A database connection.ts made from schema.sql records none of them,
- * so each `up` must find its change already made and leave it be.
+ * Lists every migration, in the order they run. A new one goes at the end,
+ * along with the same change to schema.sql, and a shipped one is never edited
+ * or moved. A database that connection.ts made from schema.sql records none of
+ * them, so each `up` must find its change already made and leave it be.
  */
 const MIGRATIONS: Migration[] = [
   { name: "0001_comment_likes", up: up0001CommentLikes },

api/db/startup.ts

@@ -13,7 +13,9 @@ import {
 } from "../config.ts";
 import { hashPassword } from "../lib/password.ts";
 
-/** Returns the time `ms` ago as an ISO string, the format dates are stored in. */
+/**
+ * Returns the time `ms` ago as an ISO string, the format dates are stored in.
+ */
 function isoAgo(ms: number): string {
   return new Date(Date.now() - ms).toISOString();
 }
@@ -21,8 +23,9 @@ function isoAgo(ms: number): string {
 /**
  * Runs after the migrations, each time the server starts. It deletes used or
  * expired reset tokens, invites past their validity, and attachments nothing
- * links to or whose resource is gone. On an instance with no users, it creates the user `admin` with the
- * password `admin`, which whoever installs it must change.
+ * links to or whose resource is gone. On an instance with no users, it creates
+ * the user `admin` with the password `admin`, which whoever installs it must
+ * change.
  */
 export async function runStartupTasks(db: DatabaseSync): Promise<void> {
   // Dates are stored as ISO strings and compared as text, so the cutoffs are

api/lib/reserved-slugs.ts

@@ -7,11 +7,11 @@
  */
 
 /**
- * The top-level path segments a category slug may not take. They are the SPA's
- * own routes (`src/App.tsx`); `api`, `ws`, `assets` and `emojibase`, which the
- * server answers before the SPA; and `manage`, a former route whose old links
- * may still be about. Keep it in step with the route table and the build's
- * top-level folders.
+ * Lists the top-level path segments a category slug may not take. They are
+ * the SPA's own routes (`src/App.tsx`); `api`, `ws`, `assets` and
+ * `emojibase`, which the server answers before the SPA; and `manage`, a
+ * former route whose old links may still be about. Keep it in step with the
+ * route table and the build's top-level folders.
  */
 export const RESERVED_SLUGS: readonly string[] = [
   "~",

api/lib/static.ts

@@ -38,7 +38,7 @@ const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
 export function routeStaticFilesFrom(
   staticPaths: string[],
 ): (context: Context<Record<string, object>>, next: Next) => Promise<void> {
-  // The last middleware: it always answers, so it never calls `next`.
+  // It is the last middleware and always answers, so it never calls `next`.
   return async (context: Context<Record<string, object>>, _next: Next) => {
     const pathname = context.request.url.pathname;
 

api/remote/fetch.ts

@@ -183,7 +183,7 @@ export async function readTextCapped(
   try {
     return new TextDecoder(charset).decode(bytes);
   } catch {
-    // An unknown label: TextDecoder throws rather than guess.
+    // TextDecoder throws on a label it doesn't know rather than guess.
     return new TextDecoder().decode(bytes);
   }
 }

api/remote/providers/bandcamp.ts

@@ -12,9 +12,10 @@ import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
 import { BANDCAMP_HOST_RE } from "../bandcamp-tralbum.ts";
 
 /**
- * Claims bandcamp.com and its subdomains, where artists have their pages. Takes
- * the embed player's URL from the page's `og:video`. The native player fetches the page's streams
- * itself at play time, through `GET /api/bandcamp/tracks`.
+ * Claims bandcamp.com and its subdomains, where artists have their pages, and
+ * takes the embed player's URL from the page's `og:video`. The native player
+ * fetches the page's streams itself at play time, through
+ * `GET /api/bandcamp/tracks`.
  */
 export const bandcampProvider: RichContentProvider = {
   name: "bandcamp",

api/services/attachment-service.ts

@@ -20,7 +20,10 @@ export function createAttachment(id: string, mime: string): void {
   ).run(id, mime, new Date().toISOString());
 }
 
-/** The kinds of resource whose saved text can link an attachment. */
+/**
+ * Stored in `attachments.resource_type` by {@link bindAttachments}, it names
+ * the kind of resource whose saved text links the attachment.
+ */
 export type AttachmentResourceType =
   | "dump"
   | "comment"

api/services/backlink-service.ts

@@ -42,8 +42,9 @@ function resolveDumpPathId(idOrSlug: string): string | null {
  * Replaces the backlinks from one text, a dump's note (`dump_comment`) or one
  * of its comments (`comment`), with the links its current `text` holds. A link
  * counts when it is a dump's page on this site, or when it is the URL a dump
- * was posted with, compared by `canonicalizeUrl` as reposts are. The dump and comment services call it on every save, and with
- * an empty `text` when a comment is deleted.
+ * was posted with, compared by `canonicalizeUrl` as reposts are. The dump and
+ * comment services call it on every save, and with an empty `text` when a
+ * comment is deleted.
  */
 export function relinkBacklinks(
   sourceType: "dump_comment" | "comment",

api/services/ws-service.ts

@@ -160,8 +160,8 @@ export function broadcastPresence(): void {
  * Tells the clients that may see a dump how it changed, for the dump service
  * after every write. `before` is null for a new dump, `after` for a deleted
  * one. A private dump's changes reach its owner's sockets alone. When a dump
- * goes private, everyone else gets `dump_deleted`; when it goes public, they get
- * `dump_created`, since to them it is new.
+ * goes private, everyone else gets `dump_deleted`; when it goes public, they
+ * get `dump_created`, since to them it is new.
  */
 export function broadcastDumpChange(
   before: Dump | null,