Add multi-board selector and scalable firmware catalog UI.

Board chips reserve future models; firmware uses searchable cards with detail pane and optional meta.json media/docs. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 19:45:24 +08:00
parent ae63378fdb
commit a59aaf1c8d
11 changed files with 788 additions and 226 deletions
--- a/README.md
+++ b/README.md
@@ -1,12 +1,14 @@
 # CYD Flasher

-Browser flasher for **Cheap Yellow Display** (ESP32-2432S028).
+Browser flasher for **Cheap Yellow Display** and related boards.

 Stack: **Next.js 15** · **Web Serial** · **esp-web-tools** · **next-intl** · **Tailwind / shadcn-style UI**

 | | |
 |---|---|
 | Locales | English (default) `/en` · 中文 `/zh` |
+| Boards | CYD 2.8\" available · 2.4\" / 3.5\" / S3 Touch shown as Soon |
+| Catalog | Searchable card grid · detail pane · media-ready |
 | SEO | `generateMetadata`, Open Graph, `/sitemap.xml`, `/robots.txt` |
 | Flash | `0x1000` bootloader · `0x8000` partitions · `0xe000` boot_app0 · `0x10000` firmware |

@@ -20,11 +22,9 @@ npm run dev

 Open **Chrome** or **Edge**: [http://localhost:3000](http://localhost:3000) (redirects to `/en`).

-1. Connect CYD with a data USB cable  
-2. Select a firmware  
-3. Click **Connect & flash** and choose the serial port (CH340 / CP210x)
-
-Production locally:
+1. Pick a **board** (only CYD 2.8\" is active for now)  
+2. Browse / search the **firmware catalog**  
+3. **Connect & flash** and choose the serial port (CH340 / CP210x)

 ```powershell
 npm run build
@@ -33,42 +33,59 @@ npm start

 ## Firmware discovery

-By default the app scans sibling projects:
+Scans sibling projects by default:

 ```text
 ../<project>/firmware/<variant>/{bootloader,partitions,boot_app0,firmware}.bin
 ```

-Examples currently picked up: `temperature`, `ld2420test`, `sgp30test`, `phtotest`, `tftest` (Pomodoro).
-
-Override search root:
+Optional rich metadata next to the bins: `meta.json` (see below).

 ```env
 CYD_FIRMWARE_ROOT=C:\Users\dsx2016\Desktop\codes\cyd
 ```

-After rebuilding a project, refresh its `firmware/` archive (each repo’s `firmware\export_from_build.ps1`), then click **Refresh** on the page.
+After rebuilding a project, run its `firmware\export_from_build.ps1`, then click **Refresh**.
+
+## Extending a firmware (media / docs)
+
+Create `meta.json` beside the `.bin` files:
+
+```json
+{
+  "boardId": "esp32-2432s028",
+  "name": "CYD Pomodoro",
+  "summary": "Short card blurb",
+  "description": "Longer detail text",
+  "tags": ["pomodoro", "touch"],
+  "media": {
+    "cover": "media/cover.webp",
+    "animation": "media/preview.gif",
+    "video": "media/demo.mp4",
+    "docs": "docs/README.md"
+  }
+}
+```
+
+- Relative media paths are served via `/api/firmware/.../media/...` (only if the file exists).
+- `docs` may also be an `https://` URL.
+- `boardId` values: `esp32-2432s028` (active), `esp32-2432s024`, `esp32-3248s035`, `esp32-s3-touch` (UI reserved).
+
+Without `meta.json`, the catalog still works from `VERSION.txt`.

 ## Public deploy

 Web Serial requires **HTTPS** (or localhost).

-1. Mirror firmwares into this repo (no Desktop path dependency):
-
 ```powershell
 npm run sync:firmware
-# or: .\scripts\sync-firmware.ps1
 ```

-2. Copy `.env.example` → `.env` and set:
-
 ```env
 NEXT_PUBLIC_SITE_URL=https://your-domain.example
 ```

-3. Deploy with Node (`npm run build && npm start`) or any Next.js host.
-
-Mirrored binaries live under `firmware/` (gitignored). Run sync in CI before build if needed.
+Then `npm run build && npm start` (or any Next.js host). `firmware/` mirror is gitignored.

 ## Scripts

@@ -83,16 +100,16 @@ Mirrored binaries live under `firmware/` (gitignored). Run sync in CI before bui
 ## Project layout

 ```text
-app/[locale]/     # SSR pages (en / zh)
-app/api/firmware/ # list · manifest · .bin
-components/       # Flasher UI + shadcn-style primitives
-messages/         # en.json · zh.json
-lib/firmware.ts   # discovery + flash offsets
-scripts/          # sync-firmware.ps1
+app/[locale]/          # SSR pages (en / zh)
+app/api/firmware/      # list · manifest · .bin · media
+components/            # board selector, catalog cards, detail
+lib/boards.ts          # board catalog
+lib/firmware.ts        # discovery + meta.json
+messages/              # en.json · zh.json
 ```

 ## 中文说明

-本机：`npm install` → `npm run dev` → Chrome/Edge 打开 http://localhost:3000 ，右上角可切中文。
+本机：`npm run dev` → http://localhost:3000 ，右上角切语言。先选板型（目前仅 2.8\" 可用），再在卡片目录里选固件刷写。

-公网：先 `npm run sync:firmware`，配置 `NEXT_PUBLIC_SITE_URL`（必须 HTTPS），再部署。固件来自各 CYD 项目的 `firmware/` 预编译包，与 PlatformIO / esptool 刷写地址一致。
+为固件增加封面 / 动画 / 视频 / 文档：在对应 `firmware/<variant>/` 下放 `meta.json` 与 `media/` 文件即可，无需改前端代码。
--- a/app/[locale]/layout.tsx
+++ b/app/[locale]/layout.tsx
@@ -80,7 +80,7 @@ export default async function LocaleLayout({ children, params }: Props) {
          <div className="bg-grid" aria-hidden />
          <div className="bg-glow" aria-hidden />

-          <header className="animate-rise relative z-10 mx-auto flex max-w-[920px] flex-wrap items-center justify-between gap-4 px-[clamp(1.25rem,4vw,3rem)] pt-6">
+          <header className="animate-rise relative z-10 mx-auto flex max-w-[1180px] flex-wrap items-center justify-between gap-4 px-[clamp(1.25rem,4vw,3rem)] pt-6">
            <div>
              <div className="flex items-center gap-2.5">
                <span
@@ -98,11 +98,11 @@ export default async function LocaleLayout({ children, params }: Props) {
            <LanguageSwitcher />
          </header>

-          <main className="relative z-10 mx-auto max-w-[920px] px-[clamp(1.25rem,4vw,3rem)] py-7 pb-12">
+          <main className="relative z-10 mx-auto max-w-[1180px] px-[clamp(1.25rem,4vw,3rem)] py-7 pb-12">
            {children}
          </main>

-          <footer className="relative z-10 mx-auto flex max-w-[920px] flex-wrap gap-x-6 gap-y-2 px-[clamp(1.25rem,4vw,3rem)] pb-10 text-xs text-[var(--muted)] opacity-85">
+          <footer className="relative z-10 mx-auto flex max-w-[1180px] flex-wrap gap-x-6 gap-y-2 px-[clamp(1.25rem,4vw,3rem)] pb-10 text-xs text-[var(--muted)] opacity-85">
            <span>{tf("offsets")}</span>
            <span>{tf("stack")}</span>
          </footer>
--- a/app/api/firmware/[project]/[variant]/media/[...path]/route.ts
+++ b/app/api/firmware/[project]/[variant]/media/[...path]/route.ts
@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+import { NextResponse } from "next/server";
+import { resolveMediaFile } from "@/lib/firmware";
+
+export const dynamic = "force-dynamic";
+
+const MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".md": "text/markdown; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".pdf": "application/pdf",
+};
+
+type Params = {
+  params: Promise<{ project: string; variant: string; path: string[] }>;
+};
+
+export async function GET(_req: Request, { params }: Params) {
+  const { project, variant, path: parts } = await params;
+  const rel = parts.join("/");
+  const abs = resolveMediaFile(project, variant, rel);
+  if (!abs) {
+    return NextResponse.json({ error: "not found" }, { status: 404 });
+  }
+
+  const ext = path.extname(abs).toLowerCase();
+  const buf = fs.readFileSync(abs);
+  return new NextResponse(buf, {
+    headers: {
+      "Content-Type": MIME[ext] || "application/octet-stream",
+      "Content-Length": String(buf.length),
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}
--- a/components/board-selector.tsx
+++ b/components/board-selector.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { BOARDS } from "@/lib/boards";
+import { cn } from "@/lib/utils";
+import { Badge } from "@/components/ui/badge";
+
+export function BoardSelector({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (boardId: string) => void;
+}) {
+  const t = useTranslations("boards");
+
+  return (
+    <div>
+      <div className="mb-3 flex items-baseline justify-between gap-3">
+        <h2 className="m-0 font-[family-name:var(--font-display)] text-[1.05rem] font-bold">
+          {t("title")}
+        </h2>
+        <p className="m-0 text-xs text-[var(--muted)]">{t("hint")}</p>
+      </div>
+      <div
+        className="grid grid-cols-2 gap-2 sm:grid-cols-4"
+        role="radiogroup"
+        aria-label={t("title")}
+      >
+        {BOARDS.map((board) => {
+          const selected = board.id === value;
+          const disabled = !board.available;
+          return (
+            <button
+              key={board.id}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              aria-disabled={disabled}
+              disabled={disabled}
+              title={disabled ? t("soon") : board.displayName}
+              onClick={() => {
+                if (!disabled) onChange(board.id);
+              }}
+              className={cn(
+                "relative flex flex-col items-start gap-1 rounded-[12px] border px-3 py-3 text-left transition-all",
+                disabled &&
+                  "cursor-not-allowed opacity-40 grayscale-[0.4]",
+                !disabled &&
+                  !selected &&
+                  "border-[var(--line)] bg-[rgba(0,0,0,0.2)] hover:border-[rgba(240,197,10,0.35)]",
+                selected &&
+                  "border-[var(--accent)] bg-[rgba(240,197,10,0.1)] shadow-[inset_0_0_0_1px_rgba(240,197,10,0.25)]"
+              )}
+            >
+              <span className="text-[0.8rem] font-semibold leading-tight">
+                {t(`items.${board.labelKey}`)}
+              </span>
+              <span className="text-[0.7rem] text-[var(--muted)]">
+                {board.chip}
+              </span>
+              {disabled && (
+                <Badge variant="muted" className="mt-1 absolute top-2 right-2">
+                  {t("soon")}
+                </Badge>
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
--- a/components/firmware-card.tsx
+++ b/components/firmware-card.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import { Film, FileText, ImageIcon } from "lucide-react";
+import type { FirmwareInfo } from "@/lib/firmware";
+import { formatBytes, cn } from "@/lib/utils";
+import { Badge } from "@/components/ui/badge";
+
+function MediaSlot({ fw, active }: { fw: FirmwareInfo; active: boolean }) {
+  const src = fw.media.animation || fw.media.cover;
+  if (src) {
+    return (
+      // Dynamic firmware media URLs — next/image needs remotePatterns per host
+      // eslint-disable-next-line @next/next/no-img-element -- local API / arbitrary media
+      <img
+        src={src}
+        alt=""
+        className="h-full w-full object-cover transition-transform duration-500 group-hover:scale-[1.03]"
+      />
+    );
+  }
+
+  const initials = fw.name
+    .replace(/[^A-Za-z0-9\u4e00-\u9fff]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((w) => w[0]?.toUpperCase() ?? "")
+    .join("");
+
+  return (
+    <div
+      className={cn(
+        "flex h-full w-full flex-col items-center justify-center gap-2 bg-[radial-gradient(ellipse_at_30%_20%,rgba(240,197,10,0.18),transparent_55%),linear-gradient(160deg,#1a1610,#0e0c09)]",
+        active && "from-[rgba(240,197,10,0.22)]"
+      )}
+    >
+      <span className="font-[family-name:var(--font-display)] text-3xl font-extrabold tracking-tight text-[var(--accent-hot)]/80">
+        {initials || "FW"}
+      </span>
+      <span className="text-[0.65rem] uppercase tracking-[0.14em] text-[var(--muted)]">
+        preview soon
+      </span>
+    </div>
+  );
+}
+
+export function FirmwareCard({
+  fw,
+  active,
+  onSelect,
+}: {
+  fw: FirmwareInfo;
+  active: boolean;
+  onSelect: () => void;
+}) {
+  const hasVideo = Boolean(fw.media.video);
+  const hasDocs = Boolean(fw.media.docs);
+  const hasCover = Boolean(fw.media.cover || fw.media.animation);
+
+  return (
+    <button
+      type="button"
+      role="option"
+      aria-selected={active}
+      onClick={onSelect}
+      className={cn(
+        "group flex flex-col overflow-hidden rounded-[14px] border text-left transition-all duration-200",
+        active
+          ? "border-[var(--accent)] bg-[rgba(240,197,10,0.08)] shadow-[0_0_0_1px_rgba(240,197,10,0.3),0_12px_32px_rgba(0,0,0,0.35)]"
+          : "border-[var(--line)] bg-[rgba(0,0,0,0.22)] hover:-translate-y-0.5 hover:border-[rgba(240,197,10,0.35)] hover:bg-[rgba(240,197,10,0.04)]"
+      )}
+    >
+      <div className="relative aspect-[16/10] w-full overflow-hidden border-b border-[var(--line)]">
+        <MediaSlot fw={fw} active={active} />
+        <div className="absolute bottom-2 left-2 flex gap-1">
+          {hasCover && (
+            <span className="rounded bg-black/55 p-1 text-[var(--ink)] backdrop-blur-sm">
+              <ImageIcon className="size-3" aria-hidden />
+            </span>
+          )}
+          {hasVideo && (
+            <span className="rounded bg-black/55 p-1 text-[var(--ink)] backdrop-blur-sm">
+              <Film className="size-3" aria-hidden />
+            </span>
+          )}
+          {hasDocs && (
+            <span className="rounded bg-black/55 p-1 text-[var(--ink)] backdrop-blur-sm">
+              <FileText className="size-3" aria-hidden />
+            </span>
+          )}
+        </div>
+        <Badge
+          variant="muted"
+          className="absolute bottom-2 right-2 bg-black/55 text-[0.65rem] backdrop-blur-sm"
+        >
+          {formatBytes(fw.size)}
+        </Badge>
+      </div>
+
+      <div className="flex flex-1 flex-col gap-2 p-3.5">
+        <h3 className="m-0 line-clamp-2 font-semibold leading-snug">{fw.name}</h3>
+        {fw.summary && (
+          <p className="m-0 line-clamp-2 text-xs leading-relaxed text-[var(--muted)]">
+            {fw.summary}
+          </p>
+        )}
+        <div className="mt-auto flex flex-wrap gap-1.5 pt-1">
+          {fw.tags.slice(0, 3).map((tag) => (
+            <Badge key={tag} variant="default" className="max-w-full truncate">
+              {tag}
+            </Badge>
+          ))}
+          {fw.date && (
+            <Badge variant="muted" className="tabular-nums">
+              {fw.date}
+            </Badge>
+          )}
+        </div>
+      </div>
+    </button>
+  );
+}
--- a/components/firmware-detail.tsx
+++ b/components/firmware-detail.tsx
@@ -0,0 +1,120 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { ExternalLink, FileText } from "lucide-react";
+import type { FirmwareInfo } from "@/lib/firmware";
+import { formatBytes } from "@/lib/utils";
+import { Badge } from "@/components/ui/badge";
+import { EspWebInstall } from "@/components/esp-web-install";
+
+export function FirmwareDetail({
+  fw,
+  serialOk,
+}: {
+  fw: FirmwareInfo | null;
+  serialOk: boolean;
+}) {
+  const t = useTranslations();
+
+  if (!fw) {
+    return (
+      <div className="rounded-[14px] border border-dashed border-[var(--line)] bg-[rgba(0,0,0,0.2)] px-5 py-10 text-center text-sm text-[var(--muted)]">
+        {t("firmware.noneSelected")}
+      </div>
+    );
+  }
+
+  const preview = fw.media.video || fw.media.animation || fw.media.cover;
+
+  return (
+    <aside className="sticky top-4 flex flex-col overflow-hidden rounded-[14px] border border-[var(--line)] bg-[color-mix(in_srgb,var(--bg-elev)_92%,transparent)] backdrop-blur-sm">
+      <div className="border-b border-[var(--line)] px-4 py-3">
+        <p className="m-0 text-xs text-[var(--muted)]">
+          {t("firmware.selectedLabel")}
+        </p>
+        <h3 className="m-0 mt-0.5 truncate font-[family-name:var(--font-display)] text-lg font-bold">
+          {fw.name}
+        </h3>
+      </div>
+
+      <div className="aspect-video w-full border-b border-[var(--line)] bg-black/40">
+        {fw.media.video ? (
+          <video
+            key={fw.media.video}
+            className="h-full w-full object-cover"
+            controls
+            playsInline
+            preload="metadata"
+            poster={fw.media.cover || undefined}
+          >
+            <source src={fw.media.video} />
+          </video>
+        ) : preview ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={preview}
+            alt=""
+            className="h-full w-full object-cover"
+          />
+        ) : (
+          <div className="flex h-full flex-col items-center justify-center gap-1 px-4 text-center">
+            <p className="m-0 text-sm text-[var(--muted)]">
+              {t("firmware.mediaPlaceholder")}
+            </p>
+            <p className="m-0 text-xs text-[var(--muted)] opacity-70">
+              meta.json → media.cover / animation / video
+            </p>
+          </div>
+        )}
+      </div>
+
+      <div className="flex flex-col gap-4 p-4">
+        {(fw.description || fw.summary) && (
+          <p className="m-0 text-sm leading-relaxed text-[var(--muted)]">
+            {fw.description || fw.summary}
+          </p>
+        )}
+
+        <div className="flex flex-wrap gap-1.5">
+          {fw.tags.map((tag) => (
+            <Badge key={tag}>{tag}</Badge>
+          ))}
+          <Badge variant="muted">{formatBytes(fw.size)}</Badge>
+          {fw.flash_size && <Badge variant="muted">{fw.flash_size}</Badge>}
+          {fw.git && <Badge variant="muted">git {fw.git}</Badge>}
+          {fw.date && <Badge variant="muted">{fw.date}</Badge>}
+        </div>
+
+        <p className="m-0 text-xs text-[var(--muted)]">
+          {fw.project}/{fw.variant} · {fw.board}
+        </p>
+
+        {fw.media.docs && (
+          <a
+            href={fw.media.docs}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 text-sm text-[var(--accent-hot)] underline-offset-2 hover:underline"
+          >
+            <FileText className="size-4" />
+            {t("firmware.docs")}
+            <ExternalLink className="size-3 opacity-70" />
+          </a>
+        )}
+
+        <EspWebInstall
+          manifest={fw.manifestUrl}
+          label={t("install.cta")}
+          disabled={!serialOk}
+        />
+
+        <ol className="m-0 list-decimal space-y-1 pl-4 text-xs text-[var(--muted)]">
+          <li>{t("install.steps.1")}</li>
+          <li>{t("install.steps.2")}</li>
+          <li>{t("install.steps.3")}</li>
+          <li>{t("install.steps.4")}</li>
+        </ol>
+      </div>
+    </aside>
+  );
+}
--- a/components/flasher-panel.tsx
+++ b/components/flasher-panel.tsx
@@ -1,14 +1,16 @@
 "use client";

-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslations } from "next-intl";
-import { RefreshCw } from "lucide-react";
+import { RefreshCw, Search } from "lucide-react";
 import type { FirmwareInfo } from "@/lib/firmware";
-import { formatBytes, cn } from "@/lib/utils";
+import { DEFAULT_BOARD_ID } from "@/lib/boards";
+import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
-import { Badge } from "@/components/ui/badge";
-import { Card, CardHeader, CardTitle } from "@/components/ui/card";
-import { EspWebInstall } from "@/components/esp-web-install";
+import { Card } from "@/components/ui/card";
+import { BoardSelector } from "@/components/board-selector";
+import { FirmwareCard } from "@/components/firmware-card";
+import { FirmwareDetail } from "@/components/firmware-detail";

 function supportsWebSerial() {
  return typeof navigator !== "undefined" && "serial" in navigator;
@@ -17,7 +19,9 @@ function supportsWebSerial() {
 export function FlasherPanel() {
  const t = useTranslations();
  const [firmwares, setFirmwares] = useState<FirmwareInfo[]>([]);
+  const [boardId, setBoardId] = useState(DEFAULT_BOARD_ID);
  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [serialOk, setSerialOk] = useState(true);
@@ -29,12 +33,7 @@ export function FlasherPanel() {
      const res = await fetch("/api/firmware", { cache: "no-store" });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      const data = (await res.json()) as { firmwares: FirmwareInfo[] };
-      const list = data.firmwares ?? [];
-      setFirmwares(list);
-      setSelectedId((prev) => {
-        if (prev && list.some((f) => f.id === prev)) return prev;
-        return list[0]?.id ?? null;
-      });
+      setFirmwares(data.firmwares ?? []);
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
      setFirmwares([]);
@@ -48,7 +47,32 @@ export function FlasherPanel() {
    void load();
  }, [load]);

-  const selected = firmwares.find((f) => f.id === selectedId) ?? null;
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return firmwares.filter((fw) => {
+      if (fw.boardId !== boardId) return false;
+      if (!q) return true;
+      const hay = [
+        fw.name,
+        fw.summary,
+        fw.description,
+        fw.project,
+        fw.variant,
+        ...fw.tags,
+      ]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+      return hay.includes(q);
+    });
+  }, [firmwares, boardId, query]);
+
+  useEffect(() => {
+    if (selectedId && filtered.some((f) => f.id === selectedId)) return;
+    setSelectedId(filtered[0]?.id ?? null);
+  }, [filtered, selectedId]);
+
+  const selected = filtered.find((f) => f.id === selectedId) ?? null;

  return (
    <div className="flex flex-col gap-5">
@@ -59,104 +83,90 @@ export function FlasherPanel() {
      )}

      <Card>
-        <CardHeader>
-          <CardTitle>{t("firmware.title")}</CardTitle>
-          <Button
-            type="button"
-            variant="ghost"
-            size="sm"
-            onClick={() => void load()}
-            disabled={loading}
-          >
-            <RefreshCw className={cn("size-3.5", loading && "animate-spin")} />
-            {t("firmware.refresh")}
-          </Button>
-        </CardHeader>
+        <BoardSelector
+          value={boardId}
+          onChange={(id) => {
+            setBoardId(id);
+            setQuery("");
+          }}
+        />
+      </Card>
+
+      <div className="grid gap-5 lg:grid-cols-[minmax(0,1fr)_minmax(280px,360px)] lg:items-start">
+        <Card className="min-w-0">
+          <div className="mb-4 flex flex-wrap items-center justify-between gap-3">
+            <div>
+              <h2 className="m-0 font-[family-name:var(--font-display)] text-[1.05rem] font-bold">
+                {t("firmware.title")}
+              </h2>
+              <p className="mt-1 m-0 text-xs text-[var(--muted)]">
+                {t("firmware.count", { count: filtered.length })}
+              </p>
+            </div>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => void load()}
+              disabled={loading}
+            >
+              <RefreshCw
+                className={cn("size-3.5", loading && "animate-spin")}
+              />
+              {t("firmware.refresh")}
+            </Button>
+          </div>
+
+          <label className="relative mb-4 block">
+            <Search
+              className="pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2 text-[var(--muted)]"
+              aria-hidden
+            />
+            <input
+              type="search"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder={t("firmware.search")}
+              className="w-full rounded-xl border border-[var(--line)] bg-[rgba(0,0,0,0.28)] py-2.5 pr-3 pl-10 text-sm text-[var(--ink)] outline-none placeholder:text-[var(--muted)] focus:border-[rgba(240,197,10,0.45)]"
+            />
+          </label>

-        <div className="flex flex-col gap-2" role="listbox" aria-label={t("firmware.title")}>
          {loading && !firmwares.length && (
-            <p className="m-0 text-sm text-[var(--muted)]">{t("firmware.scanning")}</p>
+            <p className="m-0 text-sm text-[var(--muted)]">
+              {t("firmware.scanning")}
+            </p>
          )}
          {error && (
            <p className="m-0 text-sm text-[var(--warn)]">
              {t("firmware.error", { message: error })}
            </p>
          )}
-          {!loading && !error && !firmwares.length && (
-            <p className="m-0 text-sm text-[var(--muted)]">{t("firmware.empty")}</p>
+          {!loading && !error && !filtered.length && (
+            <p className="m-0 text-sm text-[var(--muted)]">
+              {t("firmware.empty")}
+            </p>
          )}
-          {firmwares.map((fw) => {
-            const active = fw.id === selectedId;
-            const meta = [fw.board, fw.date, fw.git ? `git ${fw.git}` : null]
-              .filter(Boolean)
-              .join(" · ");
-            return (
-              <button
+
+          <div
+            className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-3"
+            role="listbox"
+            aria-label={t("firmware.title")}
+          >
+            {filtered.map((fw) => (
+              <FirmwareCard
                key={fw.id}
-                type="button"
-                role="option"
-                aria-selected={active}
-                className={cn(
-                  "grid w-full grid-cols-[auto_1fr_auto] items-center gap-x-4 gap-y-1 rounded-[10px] border px-4 py-3.5 text-left transition-colors",
-                  active
-                    ? "border-[var(--accent)] bg-[rgba(240,197,10,0.1)] shadow-[inset_0_0_0_1px_rgba(240,197,10,0.25)]"
-                    : "border-[var(--line)] bg-[rgba(0,0,0,0.2)] hover:border-[rgba(240,197,10,0.35)] hover:bg-[rgba(240,197,10,0.05)]"
-                )}
-                onClick={() => setSelectedId(fw.id)}
-              >
-                <span
-                  className={cn(
-                    "size-4 shrink-0 rounded-full border-2",
-                    active
-                      ? "border-[var(--accent)] bg-[radial-gradient(circle_at_center,var(--accent)_40%,transparent_45%)]"
-                      : "border-[var(--muted)]"
-                  )}
-                  aria-hidden
-                />
-                <span className="min-w-0">
-                  <span className="block font-semibold leading-snug">{fw.name}</span>
-                  <span className="mt-0.5 block text-xs text-[var(--muted)]">
-                    {fw.project} / {fw.variant}
-                    {meta ? ` · ${meta}` : ""}
-                  </span>
-                </span>
-                <Badge variant="muted" className="justify-self-end tabular-nums">
-                  {formatBytes(fw.size)}
-                </Badge>
-              </button>
-            );
-          })}
+                fw={fw}
+                active={fw.id === selectedId}
+                onSelect={() => setSelectedId(fw.id)}
+              />
+            ))}
+          </div>
+        </Card>
+
+        <div className="lg:sticky lg:top-4">
+          <FirmwareDetail fw={selected} serialOk={serialOk} />
        </div>
-      </Card>
-
-      <Card>
-        <div className="mb-4 rounded-lg border border-dashed border-[var(--line)] bg-[rgba(0,0,0,0.25)] px-3.5 py-3 text-sm">
-          {selected ? (
-            <>
-              {t("firmware.selectedLabel")}{" "}
-              <strong className="font-semibold text-[var(--accent-hot)]">
-                {selected.name}
-              </strong>
-              <span className="text-[var(--muted)]"> ({selected.id})</span>
-            </>
-          ) : (
-            <span className="text-[var(--muted)]">{t("firmware.noneSelected")}</span>
-          )}
-        </div>
-
-        <EspWebInstall
-          manifest={selected?.manifestUrl ?? null}
-          label={t("install.cta")}
-          disabled={!serialOk || !selected}
-        />
-
-        <ol className="mt-5 list-decimal space-y-1.5 pl-5 text-sm text-[var(--muted)]">
-          <li>{t("install.steps.1")}</li>
-          <li>{t("install.steps.2")}</li>
-          <li>{t("install.steps.3")}</li>
-          <li>{t("install.steps.4")}</li>
-        </ol>
-      </Card>
+      </div>
    </div>
  );
 }
--- a/lib/boards.ts
+++ b/lib/boards.ts
@@ -0,0 +1,62 @@
+/** Supported / planned hardware families for the flasher UI. */
+export type BoardDefinition = {
+  id: string;
+  /** Match VERSION.txt / meta board strings (case-insensitive substring). */
+  match: string[];
+  /** Translation key under boards.items.<key> */
+  labelKey: string;
+  displayName: string;
+  /** Short chip line shown on the chip */
+  chip: string;
+  available: boolean;
+};
+
+export const BOARDS: BoardDefinition[] = [
+  {
+    id: "esp32-2432s028",
+    match: ["2432s028", "esp32-2432s028"],
+    labelKey: "cyd28",
+    displayName: "CYD ESP32-2432S028",
+    chip: "ESP32 · 2.8\"",
+    available: true,
+  },
+  {
+    id: "esp32-2432s024",
+    match: ["2432s024"],
+    labelKey: "cyd24",
+    displayName: "CYD ESP32-2432S024",
+    chip: "ESP32 · 2.4\"",
+    available: false,
+  },
+  {
+    id: "esp32-3248s035",
+    match: ["3248s035"],
+    labelKey: "cyd35",
+    displayName: "CYD ESP32-3248S035",
+    chip: "ESP32 · 3.5\"",
+    available: false,
+  },
+  {
+    id: "esp32-s3-touch",
+    match: ["esp32-s3", "s3-touch"],
+    labelKey: "s3touch",
+    displayName: "ESP32-S3 Touch",
+    chip: "ESP32-S3",
+    available: false,
+  },
+];
+
+export const DEFAULT_BOARD_ID = "esp32-2432s028";
+
+export function resolveBoardId(boardField: string | null | undefined): string {
+  const raw = (boardField || "").toLowerCase();
+  if (!raw) return DEFAULT_BOARD_ID;
+  for (const b of BOARDS) {
+    if (b.match.some((m) => raw.includes(m.toLowerCase()))) return b.id;
+  }
+  return DEFAULT_BOARD_ID;
+}
+
+export function getBoard(id: string): BoardDefinition | undefined {
+  return BOARDS.find((b) => b.id === id);
+}
--- a/lib/firmware.ts
+++ b/lib/firmware.ts
@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { DEFAULT_BOARD_ID, resolveBoardId } from "@/lib/boards";

 export const REQUIRED_BINS = [
  "bootloader.bin",
@@ -15,20 +16,51 @@ export const FLASH_PARTS = [
  { file: "firmware.bin", offset: 0x10000 },
 ] as const;

+/** Optional rich metadata: place meta.json next to the .bin files. */
+export type FirmwareMedia = {
+  cover: string | null;
+  animation: string | null;
+  video: string | null;
+  docs: string | null;
+};
+
 export type FirmwareInfo = {
  id: string;
  project: string;
  variant: string;
  name: string;
+  summary: string | null;
+  description: string | null;
+  tags: string[];
  git: string | null;
  date: string | null;
  board: string;
+  boardId: string;
  flash_size: string;
  size: number;
  extras: Record<string, string>;
+  media: FirmwareMedia;
  manifestUrl: string;
 };

+type MetaJson = {
+  boardId?: string;
+  name?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  git?: string;
+  date?: string;
+  board?: string;
+  flash_size?: string;
+  media?: {
+    cover?: string;
+    animation?: string;
+    video?: string;
+    docs?: string;
+  };
+};
+
 function parseVersionTxt(text: string): Record<string, string> {
  const meta: Record<string, string> = {};
  for (const raw of text.split(/\r?\n/)) {
@@ -44,6 +76,108 @@ function parseVersionTxt(text: string): Record<string, string> {
  return meta;
 }

+function readMetaJson(dir: string): MetaJson | null {
+  const p = path.join(dir, "meta.json");
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8")) as MetaJson;
+  } catch {
+    return null;
+  }
+}
+
+function mediaUrl(
+  project: string,
+  variant: string,
+  dir: string,
+  rel: string | undefined
+): string | null {
+  if (!rel) return null;
+  if (/^https?:\/\//i.test(rel)) return rel;
+  const clean = rel.replace(/^[/\\]+/, "").replace(/\\/g, "/");
+  const abs = path.join(dir, ...clean.split("/"));
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  return `/api/firmware/${encodeURIComponent(project)}/${encodeURIComponent(variant)}/media/${clean
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}`;
+}
+
+function buildFirmwareInfo(
+  project: string,
+  variant: string,
+  dir: string
+): FirmwareInfo {
+  const versionMeta = (() => {
+    const verPath = path.join(dir, "VERSION.txt");
+    if (!fs.existsSync(verPath)) return {} as Record<string, string>;
+    try {
+      return parseVersionTxt(fs.readFileSync(verPath, "utf8"));
+    } catch {
+      return {};
+    }
+  })();
+  const json = readMetaJson(dir);
+
+  const boardField = json?.board || versionMeta.board || "ESP32-2432S028R";
+  const boardId =
+    json?.boardId || resolveBoardId(boardField) || DEFAULT_BOARD_ID;
+
+  const tags =
+    json?.tags?.filter(Boolean) ||
+    Object.keys(versionMeta)
+      .filter(
+        (k) =>
+          !["name", "git", "date", "board", "flash_size"].includes(k) &&
+          versionMeta[k]
+      )
+      .slice(0, 4);
+
+  const features = versionMeta.features;
+  const summary =
+    json?.summary ||
+    features ||
+    Object.entries(versionMeta)
+      .filter(([k]) => !["name", "git", "date", "board", "flash_size"].includes(k))
+      .map(([k, v]) => `${k}: ${v}`)
+      .slice(0, 2)
+      .join(" · ") ||
+    null;
+
+  const reserved = new Set(["name", "git", "date", "board", "flash_size", "features"]);
+  const firmwareStat = fs.statSync(path.join(dir, "firmware.bin"));
+
+  return {
+    id: `${project}/${variant}`,
+    project,
+    variant,
+    name: json?.name || versionMeta.name || `${project} (${variant})`,
+    summary,
+    description: json?.description || null,
+    tags,
+    git: json?.git || versionMeta.git || null,
+    date: json?.date || versionMeta.date || null,
+    board: boardField,
+    boardId,
+    flash_size: json?.flash_size || versionMeta.flash_size || "4MB",
+    size: firmwareStat.size,
+    extras: Object.fromEntries(
+      Object.entries(versionMeta).filter(([k]) => !reserved.has(k))
+    ),
+    media: {
+      cover: mediaUrl(project, variant, dir, json?.media?.cover),
+      animation: mediaUrl(project, variant, dir, json?.media?.animation),
+      video: mediaUrl(project, variant, dir, json?.media?.video),
+      docs: json?.media?.docs
+        ? /^https?:\/\//i.test(json.media.docs)
+          ? json.media.docs
+          : mediaUrl(project, variant, dir, json.media.docs)
+        : null,
+    },
+    manifestUrl: `/api/firmware/${encodeURIComponent(project)}/${encodeURIComponent(variant)}/manifest.json`,
+  };
+}
+
 /** Search roots: env override, bundled ./firmware, sibling projects (..). */
 export function getFirmwareSearchRoots(): string[] {
  const roots: string[] = [];
@@ -80,40 +214,11 @@ function scanProjectFirmware(
  for (const v of variants) {
    if (!v.isDirectory()) continue;
    const dir = path.join(fwRoot, v.name);
-    const missing = REQUIRED_BINS.filter((f) => !fs.existsSync(path.join(dir, f)));
-    if (missing.length) continue;
-
+    if (REQUIRED_BINS.some((f) => !fs.existsSync(path.join(dir, f)))) continue;
    const id = `${projectName}/${v.name}`;
    if (seen.has(id)) continue;
    seen.add(id);
-
-    let meta: Record<string, string> = {};
-    const verPath = path.join(dir, "VERSION.txt");
-    if (fs.existsSync(verPath)) {
-      try {
-        meta = parseVersionTxt(fs.readFileSync(verPath, "utf8"));
-      } catch {
-        /* ignore */
-      }
-    }
-
-    const firmwareStat = fs.statSync(path.join(dir, "firmware.bin"));
-    const reserved = new Set(["name", "git", "date", "board", "flash_size"]);
-    items.push({
-      id,
-      project: projectName,
-      variant: v.name,
-      name: meta.name || `${projectName} (${v.name})`,
-      git: meta.git || null,
-      date: meta.date || null,
-      board: meta.board || "ESP32-2432S028R",
-      flash_size: meta.flash_size || "4MB",
-      size: firmwareStat.size,
-      extras: Object.fromEntries(
-        Object.entries(meta).filter(([k]) => !reserved.has(k))
-      ),
-      manifestUrl: `/api/firmware/${encodeURIComponent(projectName)}/${encodeURIComponent(v.name)}/manifest.json`,
-    });
+    items.push(buildFirmwareInfo(projectName, v.name, dir));
  }
  return items;
 }
@@ -130,8 +235,6 @@ export function discoverFirmware(): FirmwareInfo[] {
  for (const root of getFirmwareSearchRoots()) {
    if (!fs.existsSync(root)) continue;

-    // Bundled: root itself is the firmware mirror (contains project folders)
-    // or root is cyd parent with project folders that contain firmware/
    let entries: fs.Dirent[];
    try {
      entries = fs.readdirSync(root, { withFileTypes: true });
@@ -141,29 +244,19 @@ export function discoverFirmware(): FirmwareInfo[] {

    for (const ent of entries) {
      if (!ent.isDirectory()) continue;
-      if (ent.name === "cydweb" || ent.name === "node_modules" || ent.name.startsWith(".")) {
+      if (
+        ent.name === "cydweb" ||
+        ent.name === "node_modules" ||
+        ent.name.startsWith(".")
+      ) {
        continue;
      }

      const projectPath = path.join(root, ent.name);
-
-      // Sibling project: ../temperature/firmware/...
      items.push(...scanProjectFirmware(projectPath, ent.name, seen));

-      // Bundled mirror: firmware/temperature/cyd_28r/...
-      // Here `root` is ./firmware and `ent` is project name; variants are direct children.
-      const maybeVariantBins = REQUIRED_BINS.every((f) =>
-        fs.existsSync(path.join(projectPath, f))
-      );
-      if (maybeVariantBins) {
-        // Unusual: project folder IS the variant — treat parent name
-        continue;
-      }
-
-      // If root is ./firmware, children are projects whose children are variants
      const nestedFw = path.join(projectPath, "firmware");
      if (!fs.existsSync(nestedFw)) {
-        // Direct: firmware/<project>/<variant>
        let variants: fs.Dirent[];
        try {
          variants = fs.readdirSync(projectPath, { withFileTypes: true });
@@ -173,37 +266,13 @@ export function discoverFirmware(): FirmwareInfo[] {
        for (const v of variants) {
          if (!v.isDirectory()) continue;
          const dir = path.join(projectPath, v.name);
-          if (REQUIRED_BINS.some((f) => !fs.existsSync(path.join(dir, f)))) continue;
+          if (REQUIRED_BINS.some((f) => !fs.existsSync(path.join(dir, f)))) {
+            continue;
+          }
          const id = `${ent.name}/${v.name}`;
          if (seen.has(id)) continue;
          seen.add(id);
-
-          let meta: Record<string, string> = {};
-          const verPath = path.join(dir, "VERSION.txt");
-          if (fs.existsSync(verPath)) {
-            try {
-              meta = parseVersionTxt(fs.readFileSync(verPath, "utf8"));
-            } catch {
-              /* ignore */
-            }
-          }
-          const firmwareStat = fs.statSync(path.join(dir, "firmware.bin"));
-          const reserved = new Set(["name", "git", "date", "board", "flash_size"]);
-          items.push({
-            id,
-            project: ent.name,
-            variant: v.name,
-            name: meta.name || `${ent.name} (${v.name})`,
-            git: meta.git || null,
-            date: meta.date || null,
-            board: meta.board || "ESP32-2432S028R",
-            flash_size: meta.flash_size || "4MB",
-            size: firmwareStat.size,
-            extras: Object.fromEntries(
-              Object.entries(meta).filter(([k]) => !reserved.has(k))
-            ),
-            manifestUrl: `/api/firmware/${encodeURIComponent(ent.name)}/${encodeURIComponent(v.name)}/manifest.json`,
-          });
+          items.push(buildFirmwareInfo(ent.name, v.name, dir));
        }
      }
    }
@@ -244,3 +313,19 @@ export function readFirmwareMeta(dir: string): Record<string, string> {
    return {};
  }
 }
+
+/** Resolve a media file under a firmware dir (path traversal safe). */
+export function resolveMediaFile(
+  project: string,
+  variant: string,
+  relPath: string
+): string | null {
+  const dir = resolveFirmwareDir(project, variant);
+  if (!dir) return null;
+  const normalized = path.normalize(relPath).replace(/^([/\\])+/, "");
+  if (normalized.startsWith("..") || path.isAbsolute(normalized)) return null;
+  const abs = path.join(dir, normalized);
+  if (!abs.startsWith(dir + path.sep) && abs !== dir) return null;
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  return abs;
+}
--- a/messages/en.json
+++ b/messages/en.json
@@ -1,33 +1,48 @@
 {
  "meta": {
    "title": "CYD Flasher — Flash Cheap Yellow Display in the browser",
-    "description": "Web Serial installer for ESP32-2432S028 (CYD). Pick a firmware and flash over USB from Chrome or Edge."
+    "description": "Web Serial installer for ESP32-2432S028 (CYD) and more boards. Pick a firmware and flash over USB from Chrome or Edge."
  },
  "brand": {
    "name": "CYD Flasher",
-    "tagline": "Browser serial flash · ESP32-2432S028"
+    "tagline": "Browser serial flash · multi-board ready"
  },
  "hero": {
-    "title": "Pick firmware, plug in USB, flash once",
-    "lede": "Scans local CYD project firmwares and writes them over Web Serial from your browser."
+    "title": "Pick a board, choose firmware, flash once",
+    "lede": "Browse project firmwares with previews and docs, then write them over Web Serial from your browser."
  },
  "browser": {
    "unsupported": "Chrome or Edge with Web Serial is required. Open this site on HTTPS or http://localhost."
  },
+  "boards": {
+    "title": "Board",
+    "hint": "More models coming soon",
+    "soon": "Soon",
+    "items": {
+      "cyd28": "CYD 2.8\"",
+      "cyd24": "CYD 2.4\"",
+      "cyd35": "CYD 3.5\"",
+      "s3touch": "ESP32-S3 Touch"
+    }
+  },
  "firmware": {
-    "title": "Available firmware",
+    "title": "Firmware catalog",
    "refresh": "Refresh",
+    "search": "Search name, tags, project…",
+    "count": "{count} available",
    "scanning": "Scanning…",
-    "empty": "No firmware found. Ensure complete firmware/*/…bin packages exist, or set CYD_FIRMWARE_ROOT.",
+    "empty": "No firmware for this board. Try another board, clear search, or set CYD_FIRMWARE_ROOT.",
    "error": "Scan failed: {message}",
-    "noneSelected": "No firmware selected",
-    "selectedLabel": "Selected:"
+    "noneSelected": "Select a firmware card to see details and flash",
+    "selectedLabel": "Selected",
+    "docs": "Documentation",
+    "mediaPlaceholder": "Animation / video / cover will appear here"
  },
  "install": {
    "cta": "Connect & flash",
    "steps": {
-      "1": "Connect CYD with a data USB cable (not charge-only).",
-      "2": "Select a firmware above.",
+      "1": "Connect the board with a data USB cable (not charge-only).",
+      "2": "Select a firmware from the catalog.",
      "3": "Click Connect & flash, then choose the serial port (CH340 / CP210x).",
      "4": "Wait for progress to finish — the board reboots automatically."
    }
--- a/messages/zh.json
+++ b/messages/zh.json
@@ -1,33 +1,48 @@
 {
  "meta": {
    "title": "CYD Flasher — 浏览器刷写 Cheap Yellow Display",
-    "description": "面向 ESP32-2432S028（CYD）的 Web Serial 刷机站。在 Chrome / Edge 中选择固件并通过 USB 刷入。"
+    "description": "面向 ESP32-2432S028（CYD）及更多板型的 Web Serial 刷机站。在 Chrome / Edge 中选择固件并通过 USB 刷入。"
  },
  "brand": {
    "name": "CYD Flasher",
-    "tagline": "浏览器串口刷机 · ESP32-2432S028"
+    "tagline": "浏览器串口刷机 · 多板型预留"
  },
  "hero": {
-    "title": "选固件，插上 USB，一键刷入",
-    "lede": "自动扫描本机 CYD 项目预编译包，在浏览器里通过 Web Serial 写入固件。"
+    "title": "选板型，选固件，一键刷入",
+    "lede": "以卡片目录浏览固件（预留动画 / 视频 / 文档），在浏览器里通过 Web Serial 写入。"
  },
  "browser": {
    "unsupported": "需要支持 Web Serial 的 Chrome 或 Edge。请通过 HTTPS 或 http://localhost 打开本页。"
  },
+  "boards": {
+    "title": "板型",
+    "hint": "更多型号即将开放",
+    "soon": "即将",
+    "items": {
+      "cyd28": "CYD 2.8\"",
+      "cyd24": "CYD 2.4\"",
+      "cyd35": "CYD 3.5\"",
+      "s3touch": "ESP32-S3 触控"
+    }
+  },
  "firmware": {
-    "title": "可用固件",
+    "title": "固件目录",
    "refresh": "刷新",
+    "search": "搜索名称、标签、项目…",
+    "count": "共 {count} 个",
    "scanning": "正在扫描…",
-    "empty": "未找到固件。请确认存在完整的 firmware/*/…bin，或设置 CYD_FIRMWARE_ROOT。",
+    "empty": "当前板型下没有固件。可换板型、清空搜索，或设置 CYD_FIRMWARE_ROOT。",
    "error": "扫描失败：{message}",
-    "noneSelected": "尚未选择固件",
-    "selectedLabel": "已选："
+    "noneSelected": "点选固件卡片查看详情并刷写",
+    "selectedLabel": "已选",
+    "docs": "文档",
+    "mediaPlaceholder": "动画 / 视频 / 封面将显示在这里"
  },
  "install": {
    "cta": "连接并刷写",
    "steps": {
-      "1": "用 USB 线连接 CYD（数据口，非仅充电）。",
-      "2": "选择上方固件。",
+      "1": "用 USB 线连接板子（数据口，非仅充电）。",
+      "2": "在目录中选择固件。",
      "3": "点「连接并刷写」，在弹窗中选串口（常见 CH340 / CP210x）。",
      "4": "等待进度完成，板子会自动重启。"
    }