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/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,
+  );