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/hooks/player/usePlayRichContent.ts

@@ -0,0 +1,91 @@
+import { useCallback, useContext, useState } from "react";
+import {
+  PlayerContext,
+  type PlayerItem,
+} from "../../contexts/player/PlayerContext.ts";
+import { BANDCAMP_PLAYER } from "../../config/playerMode.ts";
+import { resolveBandcampQueue } from "../../utils/player/bandcamp.ts";
+
+export interface PlayableRichContent {
+  type: string;
+  url: string;
+  title?: string;
+  embedUrl?: string;
+  /** Header artwork. Callers with a dump-level override should pass that. */
+  thumbnailUrl?: string;
+  /** Header subtitle — "YouTube", "SoundCloud", the site's own name. */
+  siteName?: string;
+}
+
+/**
+ * Start playback for a rich-content item.
+ *
+ * Everything except Bandcamp goes straight to the iframe embed, exactly as
+ * before. Bandcamp additionally honours GERBEUR_BANDCAMP_PLAYER: in "native"
+ * mode the page is resolved to its mp3 streams and played as a queue, which is
+ * what makes it autoplay and lets albums play through. Any failure — offline,
+ * preorder-only release, Bandcamp changing its markup — falls back to the embed.
+ *
+ * Returns whether playback actually started. A native-mode page with no stored
+ * embedUrl (an artist root, a /music index, a preorder) has nothing to fall
+ * back to, and the caller has to be told so the click isn't swallowed.
+ */
+export function usePlayRichContent() {
+  const { play, playQueue } = useContext(PlayerContext);
+  const [pending, setPending] = useState(false);
+
+  const playEmbed = useCallback(
+    (rc: PlayableRichContent, dumpHref?: string): boolean => {
+      if (!rc.embedUrl) return false;
+      play({
+        kind: "embed",
+        embedUrl: rc.embedUrl,
+        title: rc.title,
+        type: rc.type,
+        dumpHref,
+        artworkUrl: rc.thumbnailUrl,
+        subtitle: rc.siteName,
+      });
+      return true;
+    },
+    [play],
+  );
+
+  const playRichContent = useCallback(
+    async (rc: PlayableRichContent, dumpHref?: string): Promise<boolean> => {
+      const native = rc.type === "bandcamp" && BANDCAMP_PLAYER === "native";
+      if (!native) return playEmbed(rc, dumpHref);
+
+      setPending(true);
+      try {
+        const items: PlayerItem[] = await resolveBandcampQueue(rc.url, {
+          dumpHref,
+          embedUrl: rc.embedUrl,
+          // Bandcamp's own album art wins; this is the fallback if the page
+          // doesn't carry one.
+          fallbackArtworkUrl: rc.thumbnailUrl,
+        });
+        playQueue(items, 0);
+        return true;
+      } catch (err) {
+        console.warn("bandcamp: native playback unavailable, using embed", err);
+        return playEmbed(rc, dumpHref);
+      } finally {
+        setPending(false);
+      }
+    },
+    [playEmbed, playQueue],
+  );
+
+  return { playRichContent, pending };
+}
+
+/**
+ * Whether a rich-content item can be played at all. In native mode a Bandcamp
+ * page is playable even without a stored embedUrl, since the streams are
+ * resolved from the page itself.
+ */
+export function canPlayRichContent(rc: PlayableRichContent): boolean {
+  if (rc.embedUrl) return true;
+  return rc.type === "bandcamp" && BANDCAMP_PLAYER === "native";
+}