v3: src/ is documented like api/ and shared/, and the reference covers the whole repository — the frontend had no module docs, JSDoc on some components and hooks and not on others, props typed inline in half the components and in private interfaces in the rest, // comments on declarations, and no return types on 147 exported functions, so deno doc --lint over src/ found 637 errors. The rule api/ follows is applied to every non-test module of src/: a /** … @module */ block, JSDoc on every export and every field of an exported interface, /** */ for declarations and // for notes, verbs for functions ("Renders…" for a component), parameters named in the prose, {@link} only for symbols in scope, and a page's JSDoc names its route and who may see it (App.tsx's module doc lists the route table). For deno doc to show them, every exported function states its return type: components React.JSX.Element (or | null, or a portal), memo and forwardRef components their exotic types, contexts React.Context<…>, and a hook returning several things a documented Use<Name>Result interface (useAuth, useRequiredAuth, useFading, useEmojiTrigger, useMentionAutocomplete, useDumpCardLink, usePlayRichContent; FeedCacheResult, YouTubePlaylistControls and UseApiFormReturn are renamed to match). Every component that takes props takes an exported, documented <Name>Props interface — the 64 inline prop types are lifted into one, DumpFeed gets DumpFeedProps extending MainFeedProps. React types go through the global React namespace: the four default imports of react are gone, since deno doc can't follow them. Two duplicates go too: useMentionAutocomplete's UserResult was shared/'s UserSuggestion, and JournalCard re-exported JournalShape for no one; i18n.ts no longer re-exports Lingui's i18n, which its three users now import from @lingui/core. deno task doc and doc:lint now take src/ (but its tests and the generated locales), the index page gains a Frontend section linking every module by layer and domain, mod.test.ts walks src/ as well, and the docs workflow runs on changes to src/. deno doc doesn't document npm packages, so it takes a type imported from one — react-hook-form's FieldValues in the form fields, frimousse's SkinTone — for a private one; doc:lint now goes through doc-lint.ts, which fails on every diagnostic but those, 25 of them. The README states the frontend's part of the rule. No behaviour changes; 205 backend and 628 frontend tests pass, and tsc, deno check and deno lint are clean.

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

src/contexts/ws/AvatarOverrideContext.ts

@@ -1,20 +1,30 @@
+/**
+ * The avatar override context: avatars changed live, provided by WSProvider.
+ *
+ * @module
+ */
+
 import { createContext } from "react";
 
 /**
- * Live avatar state learned from `user_updated` WS events, keyed by userId.
- * Kept in its own context (not WSContext) so that `Avatar` — rendered many
- * times across feeds and comment threads — only re-renders when an avatar
- * actually changes, not on every vote/comment/dump event.
- *
- *  - `hasAvatar` reflects whether the user currently has an avatar (so a freshly
- *    added or removed avatar flips even when the surrounding list data is stale).
- *  - `version` cache-busts the avatar URL (derived from the user's `updatedAt`).
+ * Live avatar state learned from `user_updated` WS events. Kept in its own
+ * context (not WSContext) so that `Avatar` — rendered many times across feeds
+ * and comment threads — only re-renders when an avatar actually changes, not on
+ * every vote/comment/dump event.
  */
 export interface AvatarOverride {
+  /**
+   * Whether the user currently has an avatar, so a freshly added or removed
+   * avatar flips even when the surrounding list data is stale.
+   */
   hasAvatar: boolean;
+  /** Cache-busts the avatar URL (derived from the user's `updatedAt`). */
   version: number;
 }
 
-export const AvatarOverrideContext = createContext<
+/** The avatar override context, keyed by user id. */
+export const AvatarOverrideContext: React.Context<
+  Record<string, AvatarOverride>
+> = createContext<
   Record<string, AvatarOverride>
 >({});

src/contexts/ws/WSContext.ts

@@ -1,3 +1,12 @@
+/**
+ * The socket contexts, split three ways by how often each part changes, so a
+ * consumer re-renders only with what it reads: typing and presence update every
+ * few seconds while people are around, chat with every message, and a feed has
+ * no use for either. WSProvider provides all three.
+ *
+ * @module
+ */
+
 import { createContext } from "react";
 import type { ChatMessage } from "../../../shared/chat.ts";
 import type { Comment } from "../../../shared/comment.ts";
@@ -7,94 +16,155 @@ import type { OnlineUser } from "../../../shared/ws.ts";
 import type { Playlist } from "../../../shared/playlist.ts";
 import type { PublicUser } from "../../../shared/user.ts";
 
+/** A vote someone cast or withdrew. */
 export interface VoteEvent {
+  /** The dump's id. */
   dumpId: string;
+  /** Who voted. */
   voterId: string;
+  /** Whether the vote was cast or withdrawn. */
   action: "cast" | "remove";
 }
 
+/** A like someone cast or withdrew. */
 export interface LikeEvent {
+  /** The comment's id. */
   commentId: string;
+  /** Who liked it. */
   likerId: string;
+  /** Whether the like was cast or withdrawn. */
   action: "cast" | "remove";
 }
 
+/** A playlist created, changed, deleted, or whose dumps changed. */
 export interface PlaylistEvent {
+  /** What happened. */
   type: "created" | "updated" | "deleted" | "dumps_updated";
+  /** The playlist's id. */
   playlistId: string;
+  /** The playlist as it is now, when created or updated. */
   playlist?: Playlist;
+  /** The owner's id, when deleted. */
   userId?: string;
+  /** The dumps the user can see in it, in order, when its dumps changed. */
   dumpIds?: string[];
+  /** How many dumps it holds, when its dumps changed. */
   dumpCount?: number;
 }
 
+/** A comment posted, edited or deleted. */
 export interface CommentEvent {
+  /** What happened. */
   type: "created" | "deleted" | "updated";
+  /** The id of the dump it is under. */
   dumpId: string;
+  /** The comment as it is now, when posted or edited. */
   comment?: Comment;
+  /** The comment's id, when deleted. */
   commentId?: string;
 }
 
+/** A user whose public profile changed. */
 export interface UserEvent {
+  /** The user as they are now. */
   user: PublicUser;
 }
 
 /** The replied-to message, as shown in the reply bar and on a pending send. */
 export interface ChatReplyTarget {
+  /** The message's id. */
   id: string;
+  /** Its author's name. */
   author: string;
+  /** Its text. */
   body: string;
 }
 
-/** A message this client sent that the server hasn't echoed back yet — shown
- * in the list as "sending", or "failed" with a way to retry or discard it. */
+/**
+ * A message this client sent that the server hasn't echoed back yet — shown in
+ * the list as "sending", or "failed" with a way to retry or discard it.
+ */
 export interface PendingChatMessage {
+  /** The id the echo will carry back. */
   nonce: string;
+  /** The message. */
   body: string;
+  /** The message it replies to. */
   replyTo?: ChatReplyTarget;
+  /** When it was sent. */
   createdAt: Date;
+  /** Whether it is on its way or failed. */
   status: "sending" | "failed";
+  /** Why it failed. */
   error?: string;
 }
 
 /** A failed chat edit or delete, surfaced in the chat until dismissed. */
 export interface ChatError {
+  /** Distinguishes one error from the next. */
   id: number;
+  /** What went wrong. */
   message: string;
 }
 
 /**
- * The socket's state, split three ways by how often each part changes, so a
- * consumer re-renders only with what it reads: typing and presence update
- * every few seconds while people are around, chat with every message, and a
- * feed has no use for either.
+ * What {@link WSContext} holds: the connection, votes, likes, and the live
+ * dump, playlist, comment, user and notification events.
  */
 export interface WSContextValue {
+  /** The connection's state. */
   wsStatus: "connecting" | "connected" | "disconnected";
+  /** Why the socket is down, while it is. */
   wsErrorMessage: string | null;
+  /** Live vote counts, by dump id. */
   voteCounts: Record<string, number>;
+  /** The ids of the dumps the user upvoted. */
   myVotes: Set<string>;
+  /** Live like counts, by comment id. */
   likeCounts: Record<string, number>;
+  /** The ids of the comments the user likes. */
   myLikes: Set<string>;
+  /** Dumps posted (or made public) this session, newest first (capped). */
   recentDumps: Dump[];
+  /** Ids of dumps deleted this session. */
   deletedDumpIds: Set<string>;
+  /** The latest vote. */
   lastVoteEvent: VoteEvent | null;
+  /** The latest like. */
   lastLikeEvent: LikeEvent | null;
+  /** The latest edited dump. */
   lastDumpEvent: Dump | null;
+  /** The latest playlist change. */
   lastPlaylistEvent: PlaylistEvent | null;
+  /** Ids of playlists deleted this session. */
   deletedPlaylistIds: Set<string>;
+  /** The latest comment change. */
   lastCommentEvent: CommentEvent | null;
+  /** The latest profile change. */
   lastUserEvent: UserEvent | null;
+  /** How many notifications the user hasn't read. */
   unreadNotificationCount: number;
+  /** The latest notification received. */
   lastNotification: Notification | null;
   /** Increments on each WS reconnect so pages can backfill missed events. */
   connectionEpoch: number;
-  /** `shownCount`: the count on screen, used until a live one arrives. */
+  /**
+   * Upvotes a dump, optimistically. `shownCount`: the count on screen, used
+   * until a live one arrives.
+   */
   castVote: (dumpId: string, shownCount?: number) => void;
+  /** Withdraws an upvote, optimistically; `shownCount` as for `castVote`. */
   removeVote: (dumpId: string, shownCount?: number) => void;
+  /** Likes a comment, optimistically; `shownCount` as for `castVote`. */
   castCommentLike: (commentId: string, shownCount?: number) => void;
+  /** Withdraws a like, optimistically; `shownCount` as for `castVote`. */
   removeCommentLike: (commentId: string, shownCount?: number) => void;
+  /**
+   * Adds a dump this client just posted to `recentDumps`, without waiting for
+   * its broadcast.
+   */
   injectDump: (dump: Dump) => void;
+  /** Sets the unread notification count to zero. */
   clearUnreadNotifications: () => void;
 }
 
@@ -102,42 +172,65 @@ export interface WSContextValue {
 export interface WSChatContextValue {
   /** Live buffer of chat messages received this session (capped). */
   chatMessages: ChatMessage[];
-  /** Ids of chat messages deleted live this session, so fetched history can
-   * filter them out. */
+  /**
+   * Ids of chat messages deleted live this session, so fetched history can
+   * filter them out.
+   */
   deletedChatIds: Set<string>;
-  /** Messages from others since the read marker — kept by the server, so it
-   * survives reloads and agrees across tabs and devices. */
+  /**
+   * Messages from others since the read marker — kept by the server, so it
+   * survives reloads and agrees across tabs and devices.
+   */
   unreadChatCount: number;
-  /** The server's read marker: created_at of the newest message the user has
-   * seen. Null until the socket's welcome. */
+  /**
+   * The server's read marker: created_at of the newest message the user has
+   * seen. Null until the socket's welcome.
+   */
   chatReadAt: Date | null;
+  /** Messages sent and not yet echoed back. */
   pendingChatMessages: PendingChatMessage[];
+  /** The latest failed edit or delete, until dismissed. */
   chatError: ChatError | null;
-  /** Users currently composing a chat message (excludes nobody — the chatbox
-   * filters out the current user itself). Shaped like presence for avatars. */
+  /**
+   * Users currently composing a chat message (excludes nobody — the chatbox
+   * filters out the current user itself). Shaped like presence for avatars.
+   */
   typingUsers: OnlineUser[];
+  /** Sends a message, replying to `replyTo` if given. */
   sendChatMessage: (body: string, replyTo?: ChatReplyTarget) => void;
+  /** Resends the failed message `nonce`. */
   retryChatMessage: (nonce: string) => void;
+  /** Drops the failed message `nonce`. */
   discardChatMessage: (nonce: string) => void;
+  /** Edits a message. */
   editChatMessage: (id: string, body: string) => void;
+  /** Deletes a message. */
   deleteChatMessage: (id: string) => void;
+  /** Clears `chatError`. */
   dismissChatError: () => void;
   /** Moves the read marker up to the message created at `at`. */
   markChatRead: (at: Date) => void;
-  /** Folds an authoritative fetch of the stream between `from` and `to` into
-   * the live buffer after a reconnect: buffered messages in that range which
-   * the server no longer has were deleted while the socket was down. */
+  /**
+   * Folds an authoritative fetch of the stream between `from` and `to` into the
+   * live buffer after a reconnect: buffered messages in that range which the
+   * server no longer has were deleted while the socket was down.
+   */
   reconcileChat: (messages: ChatMessage[], from: Date, to: Date) => void;
-  /** Inform the server whether the user is currently composing a message, so it
-   * can show/hide the "is typing" indicator to other clients. */
+  /**
+   * Informs the server whether the user is currently composing a message, so it
+   * can show/hide the "is typing" indicator to other clients.
+   */
   setChatTyping: (typing: boolean) => void;
-  /** Inform the server whether the chatbox is open (suppresses redundant
-   * mention notifications while the user is reading chat). */
+  /**
+   * Informs the server whether the chatbox is open (suppresses redundant
+   * mention notifications while the user is reading chat).
+   */
   setChatOpen: (open: boolean) => void;
 }
 
 /** Who's connected. */
 export interface WSPresenceContextValue {
+  /** The signed-in users with a socket open. */
   onlineUsers: OnlineUser[];
 }
 
@@ -169,6 +262,7 @@ export const defaultWSValue: WSContextValue = {
   clearUnreadNotifications: () => {},
 };
 
+/** What a consumer outside any provider gets. */
 export const defaultWSChatValue: WSChatContextValue = {
   chatMessages: [],
   deletedChatIds: new Set(),
@@ -189,14 +283,25 @@ export const defaultWSChatValue: WSChatContextValue = {
   setChatOpen: () => {},
 };
 
+/** What a consumer outside any provider gets. */
 export const defaultWSPresenceValue: WSPresenceContextValue = {
   onlineUsers: [],
 };
 
-export const WSContext = createContext<WSContextValue>(defaultWSValue);
-export const WSChatContext = createContext<WSChatContextValue>(
+/** The socket context: connection, votes, likes and live events. */
+export const WSContext: React.Context<WSContextValue> = createContext<
+  WSContextValue
+>(defaultWSValue);
+/** The chat context. */
+export const WSChatContext: React.Context<WSChatContextValue> = createContext<
+  WSChatContextValue
+>(
   defaultWSChatValue,
 );
-export const WSPresenceContext = createContext<WSPresenceContextValue>(
-  defaultWSPresenceValue,
-);
+/** The presence context. */
+export const WSPresenceContext: React.Context<WSPresenceContextValue> =
+  createContext<
+    WSPresenceContextValue
+  >(
+    defaultWSPresenceValue,
+  );

src/contexts/ws/WSProvider.tsx

@@ -1,3 +1,11 @@
+/**
+ * The socket's provider: one connection per session, and the live state it
+ * feeds — presence, votes, likes, dumps, playlists, comments, users,
+ * notifications and the chat.
+ *
+ * @module
+ */
+
 import {
   type ReactNode,
   useCallback,
@@ -51,40 +59,70 @@ import { setTitleBadge } from "../../hooks/shared/useDocumentTitle.ts";
 import { playChime } from "../../utils/shared/sound.ts";
 import { mentionsUser } from "../../utils/chat/text.ts";
 
-interface WSProviderProps {
+/** The props of {@link WSProvider}. */
+export interface WSProviderProps {
+  /** The app, which reads the live state. */
   children: ReactNode;
 }
 
+/** The longest wait between reconnection attempts, in ms. */
 const MAX_BACKOFF = 30_000;
+/**
+ * How long an optimistic vote or like waits for its acknowledgement before it
+ * is rolled back, in ms.
+ */
 const ACK_TIMEOUT = 5_000;
+/**
+ * How long a connection attempt may take before the socket is shown as down, in
+ * ms.
+ */
 const CONNECT_TIMEOUT = 2_500;
-// Cap the live "new dumps" buffer so a long-lived session can't grow it without
-// bound. Feeds merge these on top of their own paginated list, so a generous
-// cap is plenty — older live arrivals are reachable via normal pagination.
+/**
+ * Cap on the live "new dumps" buffer, so a long-lived session can't grow it
+ * without bound. Feeds merge these on top of their own paginated list, so a
+ * generous cap is plenty — older live arrivals are reachable via normal
+ * pagination.
+ */
 const MAX_RECENT_DUMPS = 100;
-// Cap the live chat buffer so a long-lived session can't grow it without bound.
-// Older messages remain reachable via the /api/chat history endpoint.
+/**
+ * Cap on the live chat buffer, so a long-lived session can't grow it without
+ * bound. Older messages remain reachable via the /api/chat history endpoint.
+ */
 const MAX_CHAT_MESSAGES = 200;
-// How long a sent chat message may go without its echo before it's shown as
-// failed, and how often the read marker may go out.
+/**
+ * How long a sent chat message may go without its echo before it's shown as
+ * failed, in ms.
+ */
 const CHAT_SEND_TIMEOUT = 10_000;
+/** How often the read marker may go out, in ms. */
 const CHAT_READ_THROTTLE = 1_000;
-// A failed send whose text turns up in the resynced history within this long
-// of being sent did reach the server — only its echo was lost.
+/**
+ * A failed send whose text turns up in the resynced history within this long of
+ * being sent did reach the server — only its echo was lost.
+ */
 const CHAT_ECHO_WINDOW = 60_000;
 
+/** An optimistic vote awaiting its acknowledgement. */
 interface PendingVote {
+  /** The timer that rolls it back. */
   timeout: ReturnType<typeof setTimeout>;
+  /** Undoes it. */
   rollback: () => void;
 }
 
+/** An optimistic like awaiting its acknowledgement. */
 interface PendingLike {
+  /** The timer that rolls it back. */
   timeout: ReturnType<typeof setTimeout>;
+  /** Undoes it. */
   rollback: () => void;
 }
 
-// Minimal runtime check: verify the `type` field is a known string so we can
-// safely cast to the discriminated union and let TypeScript narrow from there.
+/**
+ * Returns `data` as a server message, or null when it isn't one. The runtime
+ * check is minimal: the `type` field must be a string, so the cast to the
+ * discriminated union is safe and TypeScript narrows from there.
+ */
 function parseWSMessage(data: string): Wire<ServerToClientMessage> | null {
   try {
     const msg = JSON.parse(data);
@@ -97,7 +135,16 @@ function parseWSMessage(data: string): Wire<ServerToClientMessage> | null {
   }
 }
 
-export function WSProvider({ children }: WSProviderProps) {
+/**
+ * Provides {@link WSContext}, {@link WSChatContext}, {@link WSPresenceContext}
+ * and {@link AvatarOverrideContext}. It connects with the session's token and
+ * reconnects with a growing backoff; each reconnect bumps `connectionEpoch` so
+ * pages backfill what they missed. Votes, likes and chat messages apply at once
+ * and are confirmed or rolled back by the server's answer. A new notification
+ * or chat message chimes, and the unread count goes in the tab title. A
+ * `force_logout` signs the user out; a change of session clears the live state.
+ */
+export function WSProvider({ children }: WSProviderProps): React.JSX.Element {
   const { token, user, logout } = useAuth();
   const userId = user?.id ?? null;
   const [wsStatus, setWSStatus] = useState<