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/utils/shared/thumbnailTint.ts

@@ -1,3 +1,13 @@
+/**
+ * Color and lettering for generated thumbnail placeholders.
+ *
+ * The tint is never painted on its own — it's mixed into the theme's surface
+ * color by CSS (`--thumb-tint`), so contrast against `--color-text` holds for
+ * any site color, in every style, in both light and dark.
+ *
+ * @module
+ */
+
 /**
  * Color and lettering for generated thumbnail placeholders.
  *
@@ -7,16 +17,20 @@
  */
 
 /**
- * `accentColor` comes from a dumped page's `theme-color`, so it's
- * attacker-controlled. Custom properties bypass CSS value parsing and get
- * substituted verbatim wherever the var is used, so the canonical form is
- * re-checked here before it ever reaches a style object.
+ * Checks whether `value` is a `#rrggbb` color. `accentColor` comes from a
+ * dumped page's `theme-color`, so it's attacker-controlled. Custom properties
+ * bypass CSS value parsing and get substituted verbatim wherever the var is
+ * used, so the canonical form is re-checked here before it ever reaches a style
+ * object.
  */
 export function isSafeHex(value: string | undefined): value is string {
   return !!value && /^#[0-9a-f]{6}$/.test(value);
 }
 
-/** FNV-1a — small, stable, and well spread across the hue circle. */
+/**
+ * Returns the FNV-1a hash of `seed` — small, stable, and well spread across the
+ * hue circle.
+ */
 function hashString(seed: string): number {
   let hash = 0x811c9dc5;
   for (let i = 0; i < seed.length; i++) {
@@ -26,11 +40,14 @@ function hashString(seed: string): number {
   return hash >>> 0;
 }
 
-/** A stable hue for a string, so the same site always gets the same tint. */
+/**
+ * Returns a stable hue for `seed`, so the same site always gets the same tint.
+ */
 export function hueFromString(seed: string): string {
   return `hsl(${hashString(seed) % 360} 55% 55%)`;
 }
 
+/** Returns the hostname of `url` without `www.`, undefined when it has none. */
 function hostnameOf(url: string | undefined): string | undefined {
   if (!url) return undefined;
   try {
@@ -41,10 +58,10 @@ function hostnameOf(url: string | undefined): string | undefined {
 }
 
 /**
- * The page's own brand color when it declared a usable one, otherwise a hue
- * derived from its hostname — so every card gets a tint, including rows saved
- * before accent extraction existed. File dumps have no hostname to hash and
- * pass `seed` (their filename) instead.
+ * Returns the page's own brand color when it declared a usable one, otherwise a
+ * hue derived from its hostname — so every card gets a tint, including rows
+ * saved before accent extraction existed. File dumps have no hostname to hash
+ * and pass `seed` (their filename) instead.
  */
 export function tintFor(
   { accentColor, url, seed }: {
@@ -57,7 +74,10 @@ export function tintFor(
   return hueFromString(seed ?? hostnameOf(url) ?? url ?? "");
 }
 
-/** The letter drawn when there's no favicon to show. */
+/**
+ * Returns the letter drawn when there's no favicon to show: the first letter or
+ * digit of `siteName`, else of the hostname of `url`.
+ */
 export function initialsFor(
   siteName: string | undefined,
   url: string | undefined,