.gitignore

@@ -36,3 +36,6 @@ coverage/
 .omc/
 .unipi/ralph/
 .unipi/logs/
+
+# Visual brainstorming companion
+.superpowers/

docs/specs/2026-05-29-popular-resources-section.md

@@ -0,0 +1,206 @@
+# 社群常用资料（热门资料）区块 — 设计与后端接口文档
+
+- 日期：2026-05-29
+- 作者：前端
+- 状态：待评审
+- 关联需求：1.6 熱門資料區
+
+---
+
+## 1. 背景与问题
+
+首页（第一页）的「热门资料」区块当前与「最新更新」区块**使用同一个组件**（`LatestUpdateRow`，图标 + 文字行卡），两个区块视觉上几乎一模一样，用户无法区分。同时该区块：
+
+- **没有封面**，不符合需求「展示封面」；
+- 与官方推荐（大封面横滑）、最新更新（图标行卡）需要在首页形成**三种不同的版式**。
+
+需求 1.6 明确：热门资料由后台数据自动排序，但**前端只展示资料、不展示具体数字**。
+
+本文档定义两部分工作：
+
+- **前端**：把该区块改造为「榜单」版式（封面 + 名次，无任何数字）。
+- **后端**：提供/调整支撑该区块的接口（本文档的主要交付物，交付给后端团队实现）。
+
+---
+
+## 2. 范围
+
+> **产品前提：第一版不做登录系统。** 凡是依赖用户身份的功能（收藏）一律顺延到 Phase 2。
+
+### Phase 1（本次）
+
+- 前端：首页区块改为榜单版式，卡片含**预览 + 下载**操作（两者都不依赖登录）。
+- 后端：
+  - `GET /api/posts?sort=popular` 热度排序；
+  - 下载计数；
+  - 管理员推荐权重字段。
+
+### Phase 2（后续，本文档仅登记，不在本次实现）
+
+- 收藏功能（依赖登录 / 用户身份系统——第一版无登录，故顺延；当前 Favorites 页仍为 Coming Soon）；
+- 分享计数；
+- 独立的「热门资料」Tab / 列表页。
+
+---
+
+## 3. 命名
+
+- 区块标题：**热门资料**（zh-CN） / **Popular assets**（en）。
+- 内部排序标识沿用 `sort=popular`，不改路由与参数。
+
+> 备注：热度时间窗（累计 vs 本周）见 §7 开放问题。
+
+---
+
+## 4. 前端排版设计（前端负责）
+
+### 4.1 组件
+
+新增榜单组件（暂名 `PopularRankRow` / `PopularRankList`），替换首页 `popular` 区块当前的 `LatestUpdateRow` 网格（桌面）与 `MessageBubble` 列表（移动）。最多展示 **5 条**。
+
+数据来源不变：继续调用 `/api/posts?sort=popular`，经现有 `postToResource` 适配为前端资源对象。
+
+### 4.2 单行结构（从左到右）
+
+| 元素 | 说明 |
+|---|---|
+| 名次徽章 | 第 1–3 名 🥇🥈🥉；第 4–5 名灰色等宽序号（`tabular-nums`） |
+| 封面缩略图 | 取 `attachments[0]` 的 `thumbnailUrl` / `posterUrl`（复用现有 `coverFor` 逻辑）；前 3 名加金色描边；无封面时回退分类图标 |
+| 标题 | 两行截断（`line-clamp-2`） |
+| Meta 行 | `类型 · 分类 · 更新时间` |
+| 操作 | **预览 + 下载**图标按钮（均不依赖登录；收藏依赖登录，见 Phase 2） |
+
+### 4.3 交互
+
+- 整行可点击，跳转 `/resource/:id`。
+- **预览**按钮：打开资料预览（图片 / 视频 / 文档），不触发下载；复用现有预览浮层逻辑。
+- **下载**按钮：复用现有 `downloadAttachment(postId, attachmentId)` 逻辑。
+- 预览 / 下载按钮均独立响应（`stopPropagation`），点击不冒泡触发整行跳转。
+
+### 4.4 响应式
+
+- 移动端：单列榜单。
+- 桌面端：居中定宽单列（保留「榜单」语义，避免退化成网格而与其他区块再次撞脸），行内加宽留白。
+
+### 4.5 铁律与状态
+
+- **零数字（指数量）**：下载量 / 收藏量 / 分享量 / 热度分等任何**数量型计数一律不显示**（即 1.6 所指「下载 500 次」类数字）。
+- **名次序号属于「排名」非「数量」**：榜单展示完整名次 1–5（前 3 名 🥇🥈🥉，4–5 灰色等宽序号）。名次表达相对排序、不暴露任何后台计数，与「避免显示数字」的意图不冲突。
+- 加载态：骨架屏。
+- 不足 5 条：沿用现有 `ComingSoon` 占位。
+
+---
+
+## 5. 后端接口契约（后端负责 · 核心交付）
+
+### 5.1 热度排序 `GET /api/posts?sort=popular`
+
+**请求参数**（沿用现有约定，无新增必填项）：
+
+```
+GET /api/posts?sort=popular&lang=zh-CN&language=<sourceLang>&limit=5
+```
+
+**排序逻辑**：后端按热度分降序返回。
+
+```
+popularityScore =
+    w_download * downloadCount
+  + w_favorite * favoriteCount
+  + w_share    * shareCount
+  + adminWeight
+```
+
+- 建议初始权重（可配置）：`w_download = 1.0`、`w_favorite = 2.0`、`w_share = 3.0`；`adminWeight` 直接相加。
+- Phase 1：`favoriteCount` / `shareCount` 暂为 0，不影响公式正确性，功能上线后自然生效。
+- 同分回退顺序：`adminWeight` 降序 → `updatedAt` 降序。
+
+**响应结构**：沿用现有 `PostListResponse`：
+
+```jsonc
+{
+  "items": [ /* Post[] */ ],
+  "nextCursor": "..."   // 可选
+}
+```
+
+**❗硬性约束**：`items` 中**不得包含**任何计数 / 分值字段（`downloadCount`、`favoriteCount`、`shareCount`、`popularityScore` 等）。这些仅用于后端排序，前端不需要也不允许展示。
+
+**Post 必含字段**（前端 `postToResource` 依赖，缺失会导致封面 / 类型 / 标题渲染异常）：
+
+```jsonc
+{
+  "id": "string",
+  "postType": "ppt | pdf | image | video | music | link | text | archive",
+  "categoryId": 0,
+  "categorySlug": "string",
+  "language": "string",
+  "attachments": [
+    {
+      "id": "string",
+      "kind": "image | video | document",
+      "url": "string",
+      "mime": "string",
+      "filename": "string",
+      "thumbnailUrl": "string?",   // 封面优先取这里
+      "posterUrl": "string?"       // 视频封面回退
+    }
+  ],
+  "isRecommended": false,
+  "publishedAt": "ISO8601",
+  "updatedAt": "ISO8601",
+  "localizations": { /* 多语言标题文本 */ },
+  "tags": ["string"]
+}
+```
+
+**封面 / 缩略图（重要）**：前端封面取值顺序为 `attachments[0].thumbnailUrl` → `posterUrl`。后端应在 body JSON 中为每条资料提供可用的封面 / 缩略图：
+
+- 图片：`thumbnailUrl`（压缩图）；
+- 视频：`posterUrl`（首帧 / 封面）；
+- 文档（ppt/pdf 等）：尽量提供后端生成的预览缩略图 `thumbnailUrl`；若暂时无法生成，前端会按**资料类型**渲染兜底封面（类型色渐变 + 类型图标），但**仍建议后端长期补齐文档缩略图**以获得最佳效果。
+
+> 前端兜底仅为优雅降级；最终视觉效果依赖后端在 body 中提供真实封面 / 缩略图。
+
+### 5.2 下载计数
+
+下载行为发生时累加 `downloadCount`（排序输入）。
+
+- 采集点：现有下载接口（前端通过 `downloadAttachment(postId, attachmentId)` 触发）。
+- 实现建议：在现有下载端点内 `++downloadCount`，或提供 `POST /api/posts/:postId/attachments/:attachmentId/download` 返回文件并计数。
+- 防刷建议（后端定夺）：同一 IP / 设备在 N 分钟内对同一资源只计一次。
+
+### 5.3 管理员推荐权重
+
+- `Post` 增加字段 `adminWeight: number`（默认 `0`）。
+- 后台资料编辑表单（`/api/admin/resources`）可设置该值，用于人工置顶热门。
+
+### 5.4 Phase 2（登记，暂不实现）
+
+- **收藏**：`POST` / `DELETE /api/posts/:id/favorite`，依赖登录 / 用户身份；累加 `favoriteCount`；提供收藏状态查询与收藏列表（支撑 Favorites 页）。
+- **分享计数**：分享行为上报 `POST /api/posts/:id/share`，`++shareCount`。
+
+---
+
+## 6. 后端内部字段（不对外暴露）
+
+`downloadCount`、`favoriteCount`、`shareCount`、`adminWeight`，以及派生的 `popularityScore`。前端响应中**不返回**。
+
+---
+
+## 7. 开放问题（需后端 / 产品确认）
+
+1. **下载接口的确切路径与契约**：前端 `downloadAttachment` 当前对应的后端端点是什么？计数挂在哪里？
+2. **热度时间窗**：是「累计热门」还是「本周 / 近 30 天热门」？若要「本周精选」语义需按时间窗统计计数。当前命名「社群常用资料」默认**累计**。
+3. **数量与分页**：首页固定 5 条；Phase 2 独立热门页是否需要分页？
+4. **防刷计数策略**的具体规则。
+5. **预览实现**：图片 / 视频可直接用 `attachment.url` / `thumbnailUrl`；文档类（ppt/pdf）在线预览是否已有渲染服务，还是仅展示封面缩略图？（预览预计**不需要后端新接口**，待确认）
+
+---
+
+## 8. 验收标准
+
+- `GET /api/posts?sort=popular` 按热度分降序返回，且响应中**无任何计数 / 分值字段**。
+- 下载行为能累加 `downloadCount` 并反映到排序。
+- 后台可设置 `adminWeight` 并影响排序。
+- 前端首页区块呈现为榜单（含封面、名次、无数字），与「最新更新」「官方推荐」区块视觉区分明显。

src/App.tsx

@@ -10,6 +10,7 @@ import { CategoryPage } from "./pages/Category";
 import { OfficialRecommendationsPage } from "./pages/OfficialRecommendations";
 import { SearchPage } from "./pages/Search";
 import { PostRedirect } from "./pages/PostRedirect";
+import { ScrollToTop } from "./components/ScrollToTop";
 import { AboutPage } from "./pages/About";
 import Favorites from "./pages/Favorites";
 import { adminUiPrefix } from "./adminPaths";
@@ -29,6 +30,7 @@ export default function App() {
             <ImageLightboxProvider>
               <VideoPlayerProvider>
                 <BrowserRouter>
+                  <ScrollToTop />
                   <Routes>
                     <Route element={<PublicLayout />}>
                       <Route path="/" element={<Home />} />

src/components/PopularRankList.tsx

@@ -0,0 +1,272 @@
+import {
+  Archive,
+  Download,
+  Eye,
+  File,
+  FileText,
+  Image as ImageIcon,
+  Link as LinkIcon,
+  LoaderCircle,
+  Music,
+  Presentation,
+  Video,
+  type LucideIcon,
+} from "lucide-react";
+import { useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { assetUrl, type Category } from "../api";
+import { useI18n } from "../i18n";
+import { resourceTypeLabel } from "../resourceTypeLabels";
+import { cleanCategoryDisplayName } from "../utils/categoryDisplay";
+import { formatDateYmd } from "../utils/format";
+import { postToResource } from "../utils/postResourceAdapter";
+import type { Attachment, Post } from "../types/post";
+import { useLightbox } from "./messageStream/overlays/ImageLightbox";
+import { useVideoPlayer } from "./messageStream/overlays/VideoPlayer";
+import { downloadAttachment } from "./messageStream/utils/downloadFile";
+import { useToast } from "./Toast";
+
+const MEDALS = ["🥇", "🥈", "🥉"];
+const MAX_ITEMS = 5;
+
+/**
+ * Fallback cover shown when a resource has no real thumbnail. A gradient tinted
+ * by resource type + the matching type icon — pure CSS, no asset needed. The
+ * backend is expected to supply real cover/thumbnail images; this is graceful
+ * degradation until it does.
+ */
+const TYPE_FALLBACK: Record<string, { gradient: string; Icon: LucideIcon }> = {
+  ppt: { gradient: "from-[#7a5a22] to-[#3a2c12]", Icon: Presentation },
+  video: { gradient: "from-[#27506a] to-[#16293a]", Icon: Video },
+  pdf: { gradient: "from-[#2f5a3f] to-[#16291d]", Icon: FileText },
+  text: { gradient: "from-[#2f5a3f] to-[#16291d]", Icon: FileText },
+  image: { gradient: "from-[#463340] to-[#241a22]", Icon: ImageIcon },
+  music: { gradient: "from-[#5a2f5a] to-[#291629]", Icon: Music },
+  link: { gradient: "from-[#2f5a55] to-[#162926]", Icon: LinkIcon },
+  archive: { gradient: "from-[#6a4a22] to-[#2f2012]", Icon: Archive },
+};
+const FALLBACK_DEFAULT = {
+  gradient: "from-[#2a2b35] to-[#191a20]",
+  Icon: File,
+};
+
+function FallbackCover({ type }: { type: string }) {
+  const { gradient, Icon } = TYPE_FALLBACK[type] ?? FALLBACK_DEFAULT;
+  return (
+    <div
+      className={`flex h-full w-full items-center justify-center bg-gradient-to-br ${gradient}`}
+    >
+      <Icon className="h-6 w-6 text-white/85" strokeWidth={1.8} />
+    </div>
+  );
+}
+
+/** Rank badge: medals for the top 3, muted tabular numbers afterwards. */
+function RankBadge({ index }: { index: number }) {
+  if (index < MEDALS.length) {
+    return (
+      <span
+        className="flex w-7 shrink-0 justify-center text-[22px] leading-none"
+        aria-label={`No.${index + 1}`}
+      >
+        {MEDALS[index]}
+      </span>
+    );
+  }
+  return (
+    <span
+      className="flex w-7 shrink-0 justify-center text-lg font-extrabold tabular-nums text-[#7d7e87]"
+      aria-label={`No.${index + 1}`}
+    >
+      {index + 1}
+    </span>
+  );
+}
+
+function PopularRankRow({
+  post,
+  index,
+  categories,
+}: {
+  post: Post;
+  index: number;
+  categories: Category[];
+}) {
+  const { t, lang } = useI18n();
+  const navigate = useNavigate();
+  const { openLightbox } = useLightbox();
+  const { openVideo } = useVideoPlayer();
+  const { showToast } = useToast();
+  const [isDownloading, setIsDownloading] = useState(false);
+  const [coverFailed, setCoverFailed] = useState(false);
+
+  const r = postToResource(post, lang, categories);
+  const cover = r.coverImage && !coverFailed ? assetUrl(r.coverImage) : "";
+  const isTop3 = index < MEDALS.length;
+
+  const first: Attachment | undefined = post.attachments[0];
+  const imageAttachments = post.attachments.filter((a) => a.kind === "image");
+
+  const handlePreview = () => {
+    if (first?.kind === "video") {
+      openVideo(first);
+      return;
+    }
+    if (imageAttachments.length > 0) {
+      openLightbox(imageAttachments, 0, r.title, post.id);
+      return;
+    }
+    // Documents / links have no inline overlay — fall through to the detail page.
+    navigate(`/resource/${post.id}`);
+  };
+
+  const handleDownload = async () => {
+    if (isDownloading || !r.downloadPostId || !r.downloadAttachmentId) return;
+    setIsDownloading(true);
+    try {
+      await downloadAttachment(
+        r.downloadPostId,
+        r.downloadAttachmentId,
+        r.title,
+      );
+      showToast(t("downloadOk"));
+    } catch {
+      showToast(t("downloadFail"), "error");
+    } finally {
+      setIsDownloading(false);
+    }
+  };
+
+  return (
+    <article className="relative flex items-center gap-3 rounded-2xl border border-ark-line bg-ark-panel p-3 transition hover:border-ark-gold/45 md:gap-4 md:p-4">
+      <button
+        type="button"
+        onClick={() => navigate(`/resource/${post.id}`)}
+        aria-label={r.title}
+        className="absolute inset-0 z-0 rounded-2xl outline-none focus-visible:ring-2 focus-visible:ring-ark-gold/70"
+      />
+
+      <RankBadge index={index} />
+
+      <div
+        className={`relative z-10 flex h-[52px] w-[64px] shrink-0 items-center justify-center overflow-hidden rounded-lg bg-[#111116] md:h-[58px] md:w-[72px] ${
+          isTop3 ? "ring-1 ring-ark-gold/45" : ""
+        }`}
+      >
+        {cover ? (
+          <img
+            src={cover}
+            alt=""
+            loading="lazy"
+            className="h-full w-full object-cover"
+            onError={() => setCoverFailed(true)}
+          />
+        ) : (
+          <FallbackCover type={r.type} />
+        )}
+      </div>
+
+      <div className="pointer-events-none relative z-10 flex min-w-0 flex-1 flex-col gap-1">
+        <div className="line-clamp-2 text-sm font-bold leading-snug text-white md:text-base">
+          {r.title}
+        </div>
+        <div className="flex items-center gap-2 text-xs text-[#9b9ca6]">
+          <span className="rounded-full bg-[#2a2b33] px-2 py-0.5 text-[#b9bac3]">
+            {resourceTypeLabel(t, r.type)}
+          </span>
+          <span className="truncate">
+            {cleanCategoryDisplayName(r.categoryName)}
+          </span>
+          <span className="text-[#55565e]">·</span>
+          <time dateTime={r.updatedAt} className="shrink-0 text-ark-muted">
+            {formatDateYmd(r.updatedAt)}
+          </time>
+        </div>
+      </div>
+
+      <div className="relative z-10 flex shrink-0 items-center gap-1">
+        <button
+          type="button"
+          onClick={handlePreview}
+          aria-label={t("preview")}
+          title={t("preview")}
+          className="flex h-9 w-9 items-center justify-center rounded-lg text-neutral-300 outline-none transition hover:bg-white/5 hover:text-ark-gold focus-visible:ring-2 focus-visible:ring-ark-gold/70"
+        >
+          <Eye className="h-[18px] w-[18px]" />
+        </button>
+        {r.isDownloadable ? (
+          <button
+            type="button"
+            onClick={handleDownload}
+            disabled={isDownloading}
+            aria-label={t("download")}
+            title={t("download")}
+            className="flex h-9 w-9 items-center justify-center rounded-lg text-neutral-300 outline-none transition hover:bg-white/5 hover:text-ark-gold focus-visible:ring-2 focus-visible:ring-ark-gold/70 disabled:opacity-60"
+          >
+            {isDownloading ? (
+              <LoaderCircle className="h-[18px] w-[18px] animate-spin" />
+            ) : (
+              <Download className="h-[18px] w-[18px]" />
+            )}
+          </button>
+        ) : null}
+      </div>
+    </article>
+  );
+}
+
+function ComingSoonRankRow({ index }: { index: number }) {
+  const { lang } = useI18n();
+  const label = lang === "zh-CN" ? "即将到来" : "Coming soon";
+  return (
+    <article
+      className="flex items-center gap-3 rounded-2xl border border-ark-line bg-ark-panel p-3 opacity-70 md:gap-4 md:p-4"
+      aria-hidden="true"
+    >
+      <RankBadge index={index} />
+      <div className="flex h-[52px] w-[64px] shrink-0 items-center justify-center overflow-hidden rounded-lg md:h-[58px] md:w-[72px]">
+        <FallbackCover type="" />
+      </div>
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <div className="text-sm font-bold text-white/80 md:text-base">
+          {label}
+        </div>
+      </div>
+    </article>
+  );
+}
+
+/**
+ * "社群常用资料" ranking list for the home page. Items arrive pre-sorted by the
+ * backend popularity score (downloads / favorites / shares / admin weight); the
+ * frontend only ever shows rank position, never any raw counts.
+ */
+export function PopularRankList({
+  posts,
+  categories,
+}: {
+  posts: Post[];
+  categories: Category[];
+}) {
+  const items = posts.slice(0, MAX_ITEMS);
+  const placeholderCount = Math.max(0, MAX_ITEMS - items.length);
+
+  return (
+    <div className="mx-auto flex max-w-[760px] flex-col gap-2.5 px-4 md:gap-3 md:px-0">
+      {items.map((post, index) => (
+        <PopularRankRow
+          key={post.id}
+          post={post}
+          index={index}
+          categories={categories}
+        />
+      ))}
+      {Array.from({ length: placeholderCount }).map((_, i) => (
+        <ComingSoonRankRow
+          key={`popular-coming-soon-${i}`}
+          index={items.length + i}
+        />
+      ))}
+    </div>
+  );
+}

src/components/RecommendedCard.tsx

@@ -97,7 +97,7 @@ export function RecommendedCard({
     <m.article
       whileHover={{ y: -4 }}
       transition={CARD_HOVER_SPRING}
-      className={`${CARD_BASE_CLASS} ${
+      className={`relative ${CARD_BASE_CLASS} ${
         layout === "grid" ? CARD_GRID_SIZE_CLASS : CARD_CAROUSEL_SIZE_CLASS
       } ${
         useFigmaDesign
@@ -107,8 +107,10 @@ export function RecommendedCard({
     >
       <Link
         to={`/resource/${r.id}`}
-        className="relative block aspect-[208/108] overflow-hidden bg-[#111116]"
+        aria-label={displayTitle}
-      >
+        className="absolute inset-0 z-10 outline-none focus-visible:ring-2 focus-visible:ring-ark-gold/70"
+      />
+      <div className="relative block aspect-[208/108] overflow-hidden bg-[#111116]">
         {cover ? (
           <img
             src={cover}
@@ -125,7 +127,7 @@ export function RecommendedCard({
             {r.badgeLabel}
           </span>
         ) : null}
-      </Link>
+      </div>
       <div
         className={
           useFigmaDesign
@@ -134,12 +136,9 @@ export function RecommendedCard({
         }
       >
         <div className="flex flex-col gap-1.5">
-          <Link
+          <h3 className="text-[15px] font-semibold leading-[21.72px] text-white line-clamp-2 transition-colors group-hover:text-ark-gold2 md:text-base md:font-bold md:leading-snug">
-            to={`/resource/${r.id}`}
-            className="text-[15px] font-semibold leading-[21.72px] text-white line-clamp-2 hover:text-ark-gold2 md:text-base md:font-bold md:leading-snug"
-          >
             {displayTitle}
-          </Link>
+          </h3>
           {useFigmaDesign ? (
             <div className="truncate text-[12px] font-normal leading-[17.376px] text-[#A8A9AE]">
               {displayCategoryName}
@@ -173,8 +172,8 @@ export function RecommendedCard({
               type="button"
               className={
                 useFigmaDesign
-                  ? "flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-[#191921] text-ark-gold outline-none transition hover:bg-[#22232D] active:scale-95 focus-visible:ring-2 focus-visible:ring-ark-gold/80 disabled:cursor-wait"
+                  ? "relative z-20 flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-[#191921] text-ark-gold outline-none transition hover:bg-[#22232D] active:scale-95 focus-visible:ring-2 focus-visible:ring-ark-gold/80 disabled:cursor-wait"
-                  : "shrink-0 rounded-lg p-1 text-ark-gold outline-none transition hover:bg-ark-gold/10 active:scale-95 focus-visible:ring-2 focus-visible:ring-ark-gold/80 disabled:cursor-wait"
+                  : "relative z-20 shrink-0 rounded-lg p-1 text-ark-gold outline-none transition hover:bg-ark-gold/10 active:scale-95 focus-visible:ring-2 focus-visible:ring-ark-gold/80 disabled:cursor-wait"
               }
               title={isDownloading ? t("downloading") : t("download")}
               aria-label={isDownloading ? t("downloading") : t("download")}

src/components/ScrollToTop.tsx

@@ -0,0 +1,22 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+
+/**
+ * Resets the window to the top on every route change. React Router does not
+ * restore scroll on client navigation, so without this a short new page would
+ * clamp to wherever the previous (taller) page was scrolled — e.g. landing at
+ * the bottom of a category page after clicking a card far down the home grid.
+ *
+ * Skips navigations that carry a hash (`#post-<id>`, `#categories`, …) so
+ * anchor / deep-link targets keep their own scroll handling.
+ */
+export function ScrollToTop() {
+  const { pathname, search, hash } = useLocation();
+
+  useEffect(() => {
+    if (hash) return;
+    window.scrollTo({ top: 0, left: 0 });
+  }, [pathname, search, hash]);
+
+  return null;
+}

src/components/messageStream/BubbleImage.tsx

@@ -0,0 +1,46 @@
+import { ImageOff } from "lucide-react";
+import { useEffect, useState } from "react";
+
+type BubbleImageProps = {
+  src: string | undefined;
+  className?: string;
+  loading?: "lazy" | "eager";
+};
+
+/**
+ * Thumbnail <img> for message bubbles. Renders with an empty alt (decorative)
+ * and, if the asset fails to load, falls back to a neutral placeholder instead
+ * of the browser's broken-image box — which would otherwise expose the raw
+ * file name via alt text.
+ */
+export function BubbleImage({ src, className, loading }: BubbleImageProps) {
+  const [failed, setFailed] = useState(false);
+
+  // Reset when the source changes so a reused element re-attempts the new src.
+  useEffect(() => {
+    setFailed(false);
+  }, [src]);
+
+  if (!src || failed) {
+    return (
+      <div
+        className={`flex items-center justify-center bg-gradient-to-br from-neutral-800 to-neutral-900 ${
+          className ?? ""
+        }`}
+        aria-hidden
+      >
+        <ImageOff className="h-8 w-8 text-neutral-600" />
+      </div>
+    );
+  }
+
+  return (
+    <img
+      src={src}
+      alt=""
+      loading={loading}
+      className={className}
+      onError={() => setFailed(true)}
+    />
+  );
+}

src/components/messageStream/bubbles/AlbumBubble.tsx

@@ -5,6 +5,7 @@ import { createPortal } from "react-dom";
 import { useI18n } from "../../../i18n";
 import type { Attachment, Post } from "../../../types/post";
 import { AttachmentDownloadPill } from "../AttachmentDownloadPill";
+import { BubbleImage } from "../BubbleImage";
 import { useLightbox } from "../overlays/ImageLightbox";
 import { autolink } from "../utils/autolink";
 import { downloadAttachment } from "../utils/downloadFile";
@@ -126,9 +127,8 @@ function ImageListDialog({
                 className="flex min-w-0 flex-1 items-center gap-3 text-left"
               >
                 <div className="h-16 w-16 shrink-0 overflow-hidden rounded-lg bg-black">
-                  <img
+                  <BubbleImage
                     src={image.thumbnailUrl ?? image.url}
-                    alt=""
                     className="h-full w-full object-cover"
                   />
                 </div>
@@ -181,11 +181,10 @@ export function AlbumBubble({ post }: { post: Post }) {
                   else openLightbox(images, i, text, post.id);
                 }}
                 className="block h-full w-full"
-                aria-label={isLastSlot ? "Open image list" : att.filename}
+                aria-label={isLastSlot ? "Open image list" : "View image"}
               >
-                <img
+                <BubbleImage
                   src={att.thumbnailUrl ?? att.url}
-                  alt={att.filename}
                   loading="lazy"
                   className="h-full w-full object-cover"
                 />

src/components/messageStream/bubbles/FileDocBubble.tsx

@@ -19,6 +19,7 @@ function AttachmentRow({ postId, att }: { postId: string; att: Attachment }) {
   const { Icon, color } = fileIcon({ mime: att.mime, filename: att.filename });
   const displayFilename = filenameWithExtension(att.filename, att.mime);
   const [isDownloading, setIsDownloading] = useState(false);
+  const [previewFailed, setPreviewFailed] = useState(false);
 
   const handleDownload = async () => {
     if (isDownloading) return;
@@ -39,11 +40,12 @@ function AttachmentRow({ postId, att }: { postId: string; att: Attachment }) {
 
   return (
     <div className="group flex h-[52px] items-center gap-3">
-      {previewUrl ? (
+      {previewUrl && !previewFailed ? (
         <img
           src={previewUrl}
-          alt={displayFilename}
+          alt=""
           loading="lazy"
+          onError={() => setPreviewFailed(true)}
           className="h-[52px] w-[52px] shrink-0 rounded-full object-cover"
         />
       ) : (

src/components/messageStream/bubbles/ImageBubble.tsx

@@ -1,5 +1,6 @@
 import type { Post } from "../../../types/post";
 import { AttachmentDownloadPill } from "../AttachmentDownloadPill";
+import { BubbleImage } from "../BubbleImage";
 import { useLightbox } from "../overlays/ImageLightbox";
 
 export function ImageBubble({ post }: { post: Post }) {
@@ -12,11 +13,10 @@ export function ImageBubble({ post }: { post: Post }) {
         type="button"
         onClick={() => openLightbox([att], 0, undefined, post.id)}
         className="block h-full w-full"
-        aria-label={att.filename}
+        aria-label="View image"
       >
-        <img
+        <BubbleImage
           src={att.url}
-          alt={att.filename}
           loading="lazy"
           className="h-full w-full object-cover"
         />

src/components/messageStream/bubbles/ImageWithTextBubble.tsx

@@ -2,6 +2,7 @@ import { useI18n } from "../../../i18n";
 import type { Post } from "../../../types/post";
 import { useLightbox } from "../overlays/ImageLightbox";
 import { AttachmentDownloadPill } from "../AttachmentDownloadPill";
+import { BubbleImage } from "../BubbleImage";
 import { autolink } from "../utils/autolink";
 import { postDisplayText } from "../utils/postText";
 
@@ -18,11 +19,10 @@ export function ImageWithTextBubble({ post }: { post: Post }) {
           type="button"
           onClick={() => openLightbox([att], 0, text, post.id)}
           className="block h-full w-full"
-          aria-label={att.filename}
+          aria-label="View image"
         >
-          <img
+          <BubbleImage
             src={att.url}
-            alt={att.filename}
             loading="lazy"
             className="h-full w-full object-cover"
           />

src/index.css

@@ -8,8 +8,12 @@ body,
   height: 100%;
 }
 
-html,
+/* Only clip horizontal overflow on <html>; this propagates to the viewport
-body {
+   and keeps the window as the vertical scroller. Adding overflow-x to <body>
+   (which has height:100%) would force its computed overflow-y to `auto`,
+   turning body into its own scroll box so window.scrollY never moves — which
+   breaks scroll-position features like the back-to-top button. */
+html {
   overflow-x: hidden;
 }
 

src/layouts/PublicLayout.tsx

@@ -669,7 +669,7 @@ export function PublicLayout() {
         </div>
       </nav>
 
-      <BackToTop />
+      {pathname === "/browse" ? <BackToTop /> : null}
     </div>
   );
 }

src/motion/variants.ts

@@ -5,7 +5,7 @@ export const EASE_OUT = [0.22, 1, 0.36, 1] as const;
 
 /** Base transition for reveal-style animations. */
 export const baseTransition: Transition = {
-  duration: 0.4,
+  duration: 0.25,
   ease: EASE_OUT,
 };
 

src/pages/Home/index.tsx

@@ -8,6 +8,7 @@ import {
   ComingSoonLatestUpdateRow,
   LatestUpdateRow,
 } from "../../components/LatestUpdateRow";
+import { PopularRankList } from "../../components/PopularRankList";
 import { RecommendedCard } from "../../components/RecommendedCard";
 import { SectionHeader } from "../../components/SectionHeader";
 import { MessageBubble } from "../../components/messageStream/MessageBubble";
@@ -246,7 +247,6 @@ export function Home() {
 
   const latestPlaceholderCount = Math.max(0, 5 - latest.length);
   const hasPopular = popular.length > 0 || popularPosts.length > 0;
-  const popularPlaceholderCount = Math.max(0, 5 - popular.length);
   const recommendedDotCount = rec.length;
   const activeRecommendedDot =
     recommendedDotCount > 0
@@ -513,27 +513,8 @@ export function Home() {
                 viewAllLabel={t("viewAll")}
               />
             </div>
-            <div className="flex flex-col gap-3 md:hidden">
+            <div className="mt-4 md:mt-7">
-              {popularPosts.slice(0, 5).map((post) => (
+              <PopularRankList posts={popularPosts} categories={cats} />
-                <MessageBubble key={post.id} post={post} />
-              ))}
-            </div>
-            <div className="mt-7 hidden grid-cols-1 gap-3 min-[576px]:grid-cols-2 md:grid md:grid-cols-2 md:gap-4 lg:grid-cols-3 xl:grid-cols-5">
-              {popular.map((r) => (
-                <LatestUpdateRow
-                  key={r.id}
-                  r={r}
-                  iconKey={iconKeyForResource(r)}
-                />
-              ))}
-              {Array.from({ length: popularPlaceholderCount }).map(
-                (_, index) => (
-                  <ComingSoonLatestUpdateRow
-                    key={`popular-coming-soon-${index}`}
-                    index={popular.length + index}
-                  />
-                ),
-              )}
             </div>
           </section>
         </Reveal>