v3: comments say what the code can't — the documentation pass wanted JSDoc on every export and every field of an exported interface, which filled the code with restatements ("The dump.", "Whether it is loading.", "The props of X.", "Renders the X.") and module docs that told a reader nothing ("The hot and new feeds, and the props every main feed of the index takes."); some were wrong as well as vague. Every comment in api/, shared/ and src/ is rewritten under one rule, now stated in the README's "Comments" section: every module and export still has a JSDoc, and it gives context (who uses it and where), usage (what a caller must know: a precondition, what it leaves to the caller, a side effect) or its place in the chain (where its input comes from, where its output goes); a field, parameter, private function or local gets one only when it adds to its parent's, and context about a whole type goes on the type; a type's doc is phrased from the value's side ("Returned to Y by X when Z", "Passed to Y by X"); full sentences, as short as they can be, no label-colon-list; // goes wherever the code isn't obvious and says why, and the section banners and narration go. Every claim was checked against the code, which turned up some forty comments that were wrong: DumpCard's claimed it was only used by the hot and new feeds, the WebSocket welcome claimed to be a socket's first message (presence comes first), UpdateUserRequest said null removes a description (it keeps it), deletedDumpIds leaves out that it also holds dumps made private, THEME_COLOR claimed to mirror index.html's, and the like. The routers' JSDoc now says where they are mounted and what becomes of a thrown APIException. doc-lint.ts lets a field without a doc through; a module or export without one still fails. No code changes; 204 backend and 628 frontend tests pass, and doc:lint, deno check, deno lint and tsc are clean.

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

api/remote/bandcamp-streams.ts

@@ -1,10 +1,9 @@
 /**
- * Resolves a Bandcamp page to its streamable tracks, at play time.
- *
- * Bandcamp's signed stream URLs expire 24h after the page fetch, so they can
- * never be baked into `rich_content` at dump-creation time the way `embedUrl`
- * is. This service is the play-time counterpart: the frontend asks for a page,
- * gets a whole tracklist back, and plays the mp3s directly from bcbits.
+ * Resolves a Bandcamp page to its streamable tracks when the native player
+ * starts it, for `GET /api/bandcamp/tracks`. The stream URLs are signed and
+ * expire 24 hours after the page is fetched, so unlike the embed URL they
+ * can't be stored in the dump's preview. The browser plays them from bcbits
+ * directly.
  *
  * @module
  */
@@ -16,19 +15,18 @@ import { BANDCAMP_HOST_RE, parseTralbum } from "./bandcamp-tralbum.ts";
 import type { Tralbum } from "../../shared/player.ts";
 
 /**
- * How long a resolved page is cached: comfortably inside the 24h signature
- * life, so a cache hit is never a URL that is about to expire mid-listen.
+ * Half the signatures' life, so a cached URL still has at least 12 hours left
+ * when it is handed out.
  */
 const TTL_MS = 12 * 60 * 60 * 1000;
-/** The most pages cached; the oldest write goes first. */
+/** The oldest write goes first. */
 const MAX_ENTRIES = 200;
 
-/** Resolved pages, by {@link cacheKey}. */
 const cache = new Map<string, Tralbum>();
 
 /**
- * Returns the cache key of `url`: a page is the same page regardless of query,
- * fragment or case.
+ * Returns `url` without its query, fragment and trailing slashes, and with its
+ * host in lowercase.
  */
 function cacheKey(url: string): string {
   try {
@@ -61,10 +59,10 @@ function writeCache(key: string, value: Tralbum): void {
 }
 
 /**
- * Fetches a Bandcamp page and returns its tracklist, cached.
- *
- * `force` bypasses the cache — used by the client's re-resolve path, so a
- * cached entry whose URLs have started 403ing can't keep being handed back.
+ * Returns the tracklist of the Bandcamp page `pageUrl`, from the cache when it
+ * was resolved in the last 12 hours. `force` skips the cache: the player sets
+ * it when it re-resolves a queue whose URLs expired or are about to, which a
+ * cached entry could hand back.
  *
  * @throws {APIException} 400 when `pageUrl` isn't a public bandcamp.com URL,
  * 502 when Bandcamp can't be reached or doesn't answer with a page, 404 when
@@ -112,9 +110,8 @@ export async function resolveBandcamp(
       "Could not reach Bandcamp",
     );
   }
-  // Every path out of here that doesn't read the body has to release it, or the
-  // connection stays open until GC. This endpoint is unauthenticated: a caller
-  // hammering random /track/<slug> URLs would otherwise leak one body a request.
+  // A body left unread keeps its connection open until GC, and this endpoint
+  // is public: every early return cancels it.
   if (!res.ok) {
     await res.body?.cancel();
     throw new APIException(
@@ -134,9 +131,8 @@ export async function resolveBandcamp(
 
   const parsed = parseTralbum(await readTextCapped(res), pageUrl);
   if (!parsed) {
-    // Covers "no data-tralbum", "hasAudio: false" and preorder-only releases
-    // with nothing streamable — all cases where the client falls back to the
-    // iframe embed rather than showing an error.
+    // No data, no audio or nothing streamable yet (a preorder). The client
+    // plays the embed instead.
     throw new APIException(
       APIErrorCode.NOT_FOUND,
       404,