v3: src/ gets one layout rule and keeps to it — each layer holds one kind of module, and every layer is split into the same domains — the previous pass sorted components into folders but left hooks, helpers and a barrel inside them, kept hooks/, utils/ and contexts/ flat, and still grouped most tests by theme. The rule: components/ holds only components (.tsx), contexts/ holds FooContext.ts + FooProvider.tsx pairs, hooks/ every hook, utils/ every non-React module, pages/ one component per route and nothing else. Each of components/, contexts/, hooks/ and utils/ is split into the same domains — auth, category, chat, comment, dump, editor, feed, form, layout, player, playlist, profile, social, theme, ws — plus shared/ for what belongs to no one domain, so the chat is components/chat, contexts/chat, hooks/chat and utils/chat. components/ui becomes components/shared to match. Out of components/: useApiForm goes to hooks/form, chat's message.ts and time.ts to utils/chat (with chatDraft and chatText, now draft.ts and text.ts), the emoji skin tone to utils/editor, the remembered volume to utils/player; player/icons.tsx is PlayerIcons.tsx. components/form/index.ts is gone: everything is imported from its own file, FormProvider straight from react-hook-form, and expectOk sits beside friendlyFetchError in utils/shared/api.ts (apiError.ts), since pages that have no form used it too. Out of pages/: the index's feed views, tab bar and presence row move to components/feed; HotFeed and NewFeed, identical but for the sort, are one DumpFeed with an order prop, which also takes over MainFeedProps from pages/index/types.ts. App is a named export like everything else. Tests mirror the tree one file per module — test/<layer>/<domain>/<Module>.test.tsx — so the themed files (hooks/misc, data, editor, sync; utils/misc, text, storage, remote, journal; contexts/providers; pages/auth and UserSubpages; layout/Fabs) are split by subject, the setup each piece needs kept and the rest dropped; the floating-button test becomes one test per button, 627 tests now. The README states the rule. No behaviour changes; the catalogues only move their source references.

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

src/components/shared/Avatar.tsx

@@ -0,0 +1,61 @@
+import { useContext, useState } from "react";
+import { API_URL } from "../../config/api.ts";
+import { AvatarOverrideContext } from "../../contexts/ws/AvatarOverrideContext.ts";
+
+interface AvatarProps {
+  userId: string;
+  username: string;
+  hasAvatar: boolean;
+  size?: number;
+  version?: number;
+}
+
+export function Avatar(
+  { userId, username, hasAvatar, size = 36, version }: AvatarProps,
+) {
+  const [imgFailed, setImgFailed] = useState(false);
+  const sizeStyle = { width: size, height: size };
+
+  // A live `user_updated` override (avatar add/remove/change) wins over the
+  // possibly-stale props the surrounding list was rendered with.
+  const override = useContext(AvatarOverrideContext)[userId];
+  const effectiveHasAvatar = override ? override.hasAvatar : hasAvatar;
+  const effectiveVersion = override ? override.version : version;
+
+  // A new image (different version/presence) is a fresh thing to try — clear
+  // any prior load failure during render rather than in an effect.
+  const imgKey = `${effectiveHasAvatar}:${effectiveVersion ?? ""}`;
+  const [prevImgKey, setPrevImgKey] = useState(imgKey);
+  if (prevImgKey !== imgKey) {
+    setPrevImgKey(imgKey);
+    setImgFailed(false);
+  }
+
+  if (effectiveHasAvatar && !imgFailed) {
+    const src = effectiveVersion
+      ? `${API_URL}/api/avatars/${userId}?v=${effectiveVersion}`
+      : `${API_URL}/api/avatars/${userId}`;
+    return (
+      <img
+        src={src}
+        alt={username}
+        title={username}
+        style={sizeStyle}
+        className="avatar-img"
+        loading="lazy"
+        decoding="async"
+        onError={() => setImgFailed(true)}
+      />
+    );
+  }
+
+  return (
+    <div
+      className="avatar-initials"
+      title={username}
+      style={{ ...sizeStyle, fontSize: size * 0.45 }}
+    >
+      {username.charAt(0).toUpperCase()}
+    </div>
+  );
+}