hd-garden 0.5.14 → 0.5.16

package/app/a2/page.tsx

@@ -1,4 +1,5 @@
 import Link from "next/link";
+import { siteHref } from "../lib/site-href";
 import { a2Slugs, readA2Article } from "../lib/a2-preview";
 
 export const metadata = {
@@ -17,7 +18,7 @@ export default function A2Index() {
       <ul className="sh-rows">
         {articles.map((article) => (
           <li className="sh-row" key={article.slug}>
-            <h3><Link href={`/a2/${article.slug}`}>{article.title}</Link></h3>
+            <h3><Link href={siteHref(`/a2/${article.slug}`)}>{article.title}</Link></h3>
             <p>{article.description}</p>
           </li>
         ))}

package/app/about/page.tsx

@@ -3,6 +3,8 @@ import { ArrowRight } from "@phosphor-icons/react/ssr";
 import { GithubProfile } from "../components/GithubProfile";
 import { PageIntro } from "../components/PageIntro";
 import { siteConfig } from "../site.config";
+import { siteHref } from "../lib/site-href";
+import { pageAlternates } from "../lib/page-alternates";
 
 const about = siteConfig.pages.about;
 const heading = about.heading ?? "关于";
@@ -17,6 +19,7 @@ const cta = about.cta ?? { href: "/blog", label: "浏览博文" };
 export const metadata = {
   title: { absolute: siteConfig.name },
   description: about.subtitle || siteConfig.description,
+  alternates: pageAlternates("/about"),
 };
 
 export default function AboutPage() {
@@ -43,7 +46,7 @@ export default function AboutPage() {
               <li key={item}>{item}</li>
             ))}
           </ul>
-          <Link href={cta.href}>
+          <Link href={siteHref(cta.href)}>
             {cta.label}
             <ArrowRight size={16} />
           </Link>

package/app/blog/[...path]/page.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { CoverImage } from "../../components/CoverImage";
 import type { Metadata } from "next";
+import { FEED_ALTERNATES } from "../../lib/page-alternates";
 import { notFound } from "next/navigation";
 import {
   extractHeadings,
@@ -42,7 +43,7 @@ export async function generateMetadata({
   return {
     title: post.title,
     description: post.description,
-    alternates: { canonical: pathname },
+    alternates: { canonical: pathname, types: FEED_ALTERNATES },
     openGraph: {
       type: "article",
       url: absoluteUrl(pathname, baseUrl),

package/app/blog/page.tsx

@@ -3,10 +3,12 @@ import { siteConfig, siteDocumentTitle } from "../site.config";
 import { BlogArchive, BlogArchiveFallback } from "../components/BlogArchive";
 import { posts } from "../lib/content";
 import { archivePosts, archiveSeries } from "../lib/archive";
+import { pageAlternates } from "../lib/page-alternates";
 
 export const metadata = {
   title: siteDocumentTitle,
   description: siteConfig.pages.blog.subtitle || siteConfig.description,
+  alternates: pageAlternates("/blog"),
 };
 
 export default function BlogIndex() {

package/app/columns/[column]/[...path]/page.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { CoverImage } from "../../../components/CoverImage";
 import type { Metadata } from "next";
+import { FEED_ALTERNATES } from "../../../lib/page-alternates";
 import { notFound } from "next/navigation";
 import { ArrowLeft, ArrowRight } from "@phosphor-icons/react/ssr";
 import {
@@ -25,6 +26,7 @@ import {
   webmentionApiEndpoint,
 } from "../../../lib/site";
 import { githubUrl, siteConfig } from "../../../site.config";
+import { siteHref } from "../../../lib/site-href";
 
 export function generateStaticParams() {
   return columns.map((entry) => ({
@@ -46,7 +48,7 @@ export async function generateMetadata({
   return {
     title: entry.title.replace(/^\d+\s*·\s*/u, ""),
     description: entry.description,
-    alternates: { canonical: pathname },
+    alternates: { canonical: pathname, types: FEED_ALTERNATES },
     openGraph: {
       type: "article",
       url: absoluteUrl(pathname, baseUrl),
@@ -88,7 +90,7 @@ export default async function ColumnEntryPage({
   return (
     <main className="column-reading-page">
       <aside className="series-nav">
-        <Link href="/columns" className="back-link">
+        <Link href={siteHref("/columns")} className="back-link">
           <ArrowLeft size={15} />
           所有专栏
         </Link>

package/app/columns/page.tsx

@@ -3,10 +3,12 @@ import Link from "next/link";
 import { columnHref, columns } from "../lib/content";
 import { ContentEmptyState } from "../components/ContentEmptyState";
 import { siteConfig, siteDocumentTitle } from "../site.config";
+import { pageAlternates } from "../lib/page-alternates";
 
 export const metadata = {
   title: siteDocumentTitle,
   description: siteConfig.pages.columns.subtitle || siteConfig.description,
+  alternates: pageAlternates("/columns"),
 };
 
 function day(value: string) {

package/app/components/ArticleTags.tsx

@@ -1,5 +1,6 @@
 import Link from "next/link";
 import { articleTagHref } from "../lib/tag-filter";
+import { siteHref } from "../lib/site-href";
 
 /** Tags under an article title. Link, so following one is a client navigation like the rest of the site. */
 export function ArticleTags({ tags }: { tags?: string[] }) {
@@ -9,7 +10,7 @@ export function ArticleTags({ tags }: { tags?: string[] }) {
     <ul className="article-tagrow" aria-label="标签">
       {list.map((tag) => (
         <li key={tag}>
-          <Link className="tag-chip p-category" href={articleTagHref(tag)}>
+          <Link className="tag-chip p-category" href={siteHref(articleTagHref(tag))}>
             #{tag}
           </Link>
         </li>

package/app/components/BlogArchive.tsx

@@ -16,6 +16,7 @@ import {
   visibleTagOptions,
 } from "../lib/tag-filter";
 import { ContentEmptyState } from "./ContentEmptyState";
+import { siteHref } from "../lib/site-href";
 
 function day(value: string) {
   const date = new Date(value);
@@ -29,8 +30,8 @@ function day(value: string) {
 }
 
 // Kept local: importing ../lib/content here would pull every post body into the client bundle.
-const postHref = (post: Pick<ArchivePost, "path">) => `/blog/${post.path}`;
-const columnIndexHref = (slug: string) => `/columns/#${slug}`;
+const postHref = (post: Pick<ArchivePost, "path">) => siteHref(`/blog/${post.path}`);
+const columnIndexHref = (slug: string) => siteHref(`/columns/#${slug}`);
 
 function ColumnLabel({ column }: { column?: ArchivePost["column"] }) {
   return column ? <Link className="cat" href={columnIndexHref(column.slug)}>{column.title}</Link> : null;

package/app/components/ContentEmptyState.tsx

@@ -2,6 +2,7 @@
 
 import Link from "next/link";
 import { ArrowRight, Article, Books, Quotes } from "@phosphor-icons/react/ssr";
+import { siteHref } from "../lib/site-href";
 
 const emptyContent = {
   posts: {
@@ -44,7 +45,7 @@ export function ContentEmptyState({ kind }: { kind: keyof typeof emptyContent })
         <h2 id={`${kind}-empty-title`}>{content.title}</h2>
         <p>{content.description}</p>
       </div>
-      <Link href={content.actionHref}>
+      <Link href={siteHref(content.actionHref)}>
         {content.actionLabel}
         <ArrowRight size={17} />
       </Link>

package/app/components/MarkdownArticle.tsx

@@ -14,13 +14,15 @@ import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
 import rehypeKatex from "rehype-katex";
 import rehypeSlug from "rehype-slug";
-import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import rehypeHighlight from "rehype-highlight";
+import { rehypeHeadingAnchors } from "../../ui/garden/heading-anchors.mjs";
 import { MermaidDiagram } from "./MermaidDiagram";
 import { MarkdownImage } from "./MarkdownImage";
 import { CodeCopy } from "./garden/chrome";
 import { CodeDiff } from "./garden/chrome";
 import { GardenBlock } from "./garden/GardenBlock";
+import { GardenFile } from "./garden/GardenFile";
+import { readGardenPayload } from "../lib/remark-garden.mjs";
 import { imageSizes, linkAssets } from "@garden/generated-content";
 import { imageDimensions, lookupImageSize } from "../../ui/garden/image-dims.mjs";
 import { siteConfig, siteLinks } from "@garden/site-config";
@@ -30,6 +32,8 @@ import { columnHref, columns, postHref, posts, thoughts } from "../lib/content";
 import { LinkCardRefresh } from "./LinkCardRefresh";
 import { linkHost } from "../../scripts/link-meta-core.mjs";
 import { cardDate } from "../../ui/garden/card-refresh.mjs";
+import { siteHref } from "../lib/site-href";
+import { codeLanguageLabel } from "../../ui/garden/code-language.mjs";
 
 // Full URLs back to this site are internal links, written as root-relative paths.
 const sameSite = sameSiteMatcher(siteLinks?.address ?? "", siteLinks?.basePath ?? "");
@@ -48,6 +52,8 @@ const internalRoute = internalLinkResolver({
     ...thoughts.map((thought) => `/thoughts/${thought.slug}`),
   ],
   basePath: siteLinks?.basePath ?? "",
+  // Same shape as every other address in the site (the slash follows trailingSlash).
+  format: siteHref,
 });
 
 /** The site's favicon, downloaded at build time; nothing when there is none. */
@@ -238,9 +244,12 @@ export function MarkdownArticle({ content }: { content: string }) {
         standalone={(props.dataStandalone ?? props["data-standalone"]) === "true"}
       />
     ),
-    "garden-block": (props: { dataPayload?: string; "data-payload"?: string }) => (
-      <GardenBlock dataPayload={props.dataPayload ?? props["data-payload"]} />
-    ),
+    "garden-block": (props: { dataPayload?: string; "data-payload"?: string }) => {
+      const payload = props.dataPayload ?? props["data-payload"];
+      const block = readGardenPayload(payload);
+      if (block?.name === "file" && !block.error) return <GardenFile props={(block.props ?? {}) as Record<string, unknown>} />;
+      return <GardenBlock dataPayload={payload} />;
+    },
     "garden-codediff": (props: {
       children?: ReactNode;
       dataDiff?: string;
@@ -263,7 +272,8 @@ export function MarkdownArticle({ content }: { content: string }) {
           rehypeRaw,
           rehypeKatex,
           rehypeSlug,
-          [rehypeAutolinkHeadings, { behavior: "wrap", properties: { className: ["h-anchor"] } }],
+          // Not rehype-autolink-headings "wrap": a heading with a link in it would nest <a> in <a> (React #418).
+          [rehypeHeadingAnchors, { className: ["h-anchor"] }],
           rehypeHighlight,
         ]}
         components={{
@@ -333,7 +343,7 @@ export function MarkdownArticle({ content }: { content: string }) {
 
             return (
               <CodeCopy>
-                <pre className="code" {...preProps} data-language={language?.toUpperCase()}>
+                <pre className="code" {...preProps} data-language={codeLanguageLabel(language) || undefined}>
                   {children}
                 </pre>
               </CodeCopy>

package/app/components/SiteHeader.tsx

@@ -19,6 +19,7 @@ import { resolveDark, themeSwitchProps } from "../../ui/garden/theme.mjs";
 import { SITE_NAV, isCurrentNav } from "../../ui/garden/site-nav.mjs";
 import { createIdbStore, loadFullIndex, saveDataOn, whenIdleAfterLoad } from "../../ui/garden/search-full.mjs";
 import { siteConfig } from "../site.config";
+import { siteHref } from "../lib/site-href";
 
 /** One entry of /search-index.json: titles, tags, dates and a short excerpt, never the full body. */
 type SearchRecord = {
@@ -86,7 +87,7 @@ function loadSearchEngine() {
   return engineLoad;
 }
 
-const nav = SITE_NAV;
+const nav = SITE_NAV.map((item) => ({ ...item, href: siteHref(item.href) }));
 
 function rangesFor(
   matches: readonly SearchMatch[] | undefined,
@@ -301,6 +302,10 @@ export function SiteHeader() {
 
   return (
     <>
+      {/* Targets for the no-JavaScript menu links below. Fixed and outside the sticky header, so
+          following #sh-menu-on or #sh-menu-off never scrolls the page (the TOC drawer works the same way). */}
+      <span className="sh-menu-target" id="sh-menu-on" aria-hidden="true" />
+      <span className="sh-menu-target" id="sh-menu-off" aria-hidden="true" />
       <header className="sh-header" id="site-header">
         <div className="sh-bar">
           <Link href="/" className="sh-word">
@@ -343,11 +348,11 @@ export function SiteHeader() {
               {menuOpen ? <X size={18} /> : <span aria-hidden="true">☰</span>}
             </button>
             {/* Without JavaScript the button above cannot open anything: these two links take its place
-                and open or close the menu through :target, like the TOC drawer (shell.css). */}
-            <a className="sh-icon sh-menu-nojs" id="sh-menu-open" href="#sh-menu" aria-label="打开菜单">
+                and open or close the menu through :target on the fixed anchors above (shell.css). */}
+            <a className="sh-icon sh-menu-nojs" id="sh-menu-open" href="#sh-menu-on" aria-label="打开菜单">
               <span aria-hidden="true">☰</span>
             </a>
-            <a className="sh-icon sh-menu-nojs-close" href="#site-header" aria-label="关闭菜单">
+            <a className="sh-icon sh-menu-nojs-close" href="#sh-menu-off" aria-label="关闭菜单">
               <X size={18} />
             </a>
           </div>
@@ -429,7 +434,7 @@ export function SiteHeader() {
                     ref={(node) => {
                       resultRefs.current[index] = node;
                     }}
-                    href={result.item.path}
+                    href={siteHref(result.item.path)}
                     onClick={closeSearch}
                     onFocus={() => setActiveResult(index)}
                     role="option"

package/app/components/TagRedirect.tsx

@@ -3,13 +3,14 @@
 import { useRouter, useSearchParams } from "next/navigation";
 import { useEffect } from "react";
 import { ARTICLE_TAG_LIST, TAG_PARAM, selectedTags, tagFilterHref } from "../lib/tag-filter";
+import { siteHref } from "../lib/site-href";
 
 /** Old `/tags?t=X` links open the same filter on `/blog/?t=X`. */
 export function TagRedirect() {
   const router = useRouter();
   const params = useSearchParams();
   const tags = selectedTags(params.getAll(TAG_PARAM));
-  const target = tags.length ? tagFilterHref(tags, ARTICLE_TAG_LIST) : "";
+  const target = tags.length ? siteHref(tagFilterHref(tags, ARTICLE_TAG_LIST)) : "";
   useEffect(() => {
     if (target) router.replace(target);
   }, [router, target]);

package/app/components/ThoughtCard.tsx

@@ -14,6 +14,7 @@ import {
 } from "../lib/content";
 import { githubUrl, siteConfig } from "../site.config";
 import { MarkdownArticle } from "./MarkdownArticle";
+import { siteHref } from "../lib/site-href";
 
 const icons = {
   image: ImageSquare,
@@ -68,7 +69,7 @@ export function ThoughtCard({
 
   return (
     <article id={thought.slug} className="thought-card h-entry">
-      <Link className="u-url sr-only" href={`/thoughts/${thought.slug}`}>
+      <Link className="u-url sr-only" href={siteHref(`/thoughts/${thought.slug}`)}>
         {thought.title} 永久链接
       </Link>
       <a
@@ -232,7 +233,7 @@ export function ThoughtCard({
       )}
 
       {showPermalink && (
-        <Link className="thought-permalink" href={`/thoughts/${thought.slug}`}>
+        <Link className="thought-permalink" href={siteHref(`/thoughts/${thought.slug}`)}>
           永久链接
           <ArrowUpRight size={15} />
         </Link>

package/app/components/garden/FilePreview.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import { useCallback, useEffect, useId, useRef, useState, type FocusEvent, type MouseEvent } from "react";
+import { createPortal } from "react-dom";
+import { previewBody, previewFrameProps } from "../../../ui/garden/file-block.mjs";
+import { ActionGlyph, FileGlyph } from "./file-icons";
+
+export type PreviewFile = {
+  title: string;
+  name: string;
+  meta: string;
+  icon: string;
+  url: string;
+  preview: "md" | "html" | "pdf";
+  /** Markdown only: the preview rendered at build time, in its own file. */
+  src?: string;
+};
+
+type Loaded = { state: "idle" | "loading" | "error" } | { state: "ready"; html: string };
+
+/**
+ * The 预览 control and its drawer. Markdown is fetched from its prerendered
+ * file the first time the drawer opens (the page does not carry it); HTML runs
+ * in a sandbox without the site's origin; PDF uses the browser's own viewer.
+ * The control is a link: without JavaScript it opens the same preview (or the
+ * file) in a new tab, next to the card's download link.
+ */
+export function FilePreview({ file, compact }: { file: PreviewFile; compact: boolean }) {
+  const [open, setOpen] = useState(false);
+  const [loaded, setLoaded] = useState<Loaded>({ state: "idle" });
+  const trigger = useRef<HTMLAnchorElement>(null);
+  const request = useRef<AbortController | null>(null);
+  const panel = useRef<HTMLElement>(null);
+  const closeButton = useRef<HTMLButtonElement>(null);
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const titleId = useId();
+
+  const close = useCallback(() => {
+    request.current?.abort();
+    setOpen(false);
+    trigger.current?.focus();
+  }, []);
+
+  const load = useCallback(() => {
+    if (!file.src) return;
+    request.current?.abort();
+    const controller = new AbortController();
+    request.current = controller;
+    setLoaded({ state: "loading" });
+    fetch(file.src, { signal: controller.signal })
+      .then((response) => {
+        if (!response.ok) throw new Error(String(response.status));
+        return response.text();
+      })
+      .then((text) => {
+        if (request.current !== controller) return;
+        const html = previewBody(text);
+        setLoaded(html ? { state: "ready", html } : { state: "error" });
+      })
+      .catch(() => {
+        if (request.current !== controller) return;
+        // Closed before it arrived: the next open starts again.
+        setLoaded(controller.signal.aborted ? { state: "idle" } : { state: "error" });
+      });
+  }, [file.src]);
+
+  useEffect(() => {
+    if (!open) return;
+    const root = document.documentElement;
+    root.classList.add("ux-lock");
+    closeButton.current?.focus();
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        close();
+        return;
+      }
+      if (event.key !== "Tab" || !panel.current) return;
+      const focusable = [...panel.current.querySelectorAll<HTMLElement>("a[href], button, iframe, [tabindex]:not([tabindex='-1'])")].filter((element) => !element.hasAttribute("data-gf-sentinel"));
+      if (!focusable.length) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => {
+      root.classList.remove("ux-lock");
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [open, close]);
+
+  // Focus loops inside the drawer even when it starts in the iframe.
+  // After the iframe: Tab left it, so go round to the drawer's first control.
+  const fromAfter = () => {
+    panel.current?.querySelector<HTMLElement>(".gf-dh a[href], .gf-dh button")?.focus();
+  };
+  // Before the iframe: coming forward from the header, go on into the iframe;
+  // coming back out of it (Shift+Tab, or from outside), go to the close button.
+  const fromBefore = (event: FocusEvent<HTMLSpanElement>) => {
+    const from = event.relatedTarget as Node | null;
+    if (from && panel.current?.querySelector(".gf-dh")?.contains(from)) frameRef.current?.focus();
+    else closeButton.current?.focus();
+  };
+
+  // A plain click opens the drawer; a modified click (new tab, new window) keeps the link.
+  const openDrawer = (event: MouseEvent<HTMLAnchorElement>) => {
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    setOpen(true);
+    // Fetched on first open and kept; a failed or interrupted load starts again.
+    if (file.preview === "md" && loaded.state !== "ready" && loaded.state !== "loading") load();
+  };
+
+  const frame = previewFrameProps(file) as { src: string; title: string; referrerPolicy: "no-referrer"; sandbox?: string } | null;
+  const drawer = open
+    ? createPortal(
+        <div className="gf-layer">
+          <div className="gf-scrim" onClick={close} aria-hidden="true" />
+          <aside ref={panel} className="gf-drawer" role="dialog" aria-modal="true" aria-labelledby={titleId} data-preview={file.preview}>
+            <div className="gf-dh">
+              <span className="gf-ico" aria-hidden="true"><FileGlyph kind={file.icon} /></span>
+              <div className="gf-main">
+                <div className="gf-name" id={titleId} title={file.title}>{file.title}</div>
+                {file.meta ? <div className="gf-meta">{file.meta}</div> : null}
+              </div>
+              <div className="gf-act">
+                <a className="gf-btn icon" href={file.url} download={file.name} aria-label={`下载 ${file.name}`} title="下载">
+                  <ActionGlyph name="download" />
+                </a>
+                <a className="gf-btn icon" href={file.url} target="_blank" rel="noopener noreferrer" aria-label={`在新标签页打开 ${file.name}`} title="在新标签页打开">
+                  <ActionGlyph name="external" />
+                </a>
+                <button ref={closeButton} type="button" className="gf-btn icon" onClick={close} aria-label="关闭预览" title="关闭">
+                  <ActionGlyph name="close" />
+                </button>
+              </div>
+            </div>
+            {!frame ? (
+              <div className="gf-db" aria-busy={loaded.state === "loading" ? "true" : undefined}>
+                {loaded.state === "ready" ? (
+                  <div className="markdown-body prose gf-doc" dangerouslySetInnerHTML={{ __html: loaded.html }} />
+                ) : loaded.state === "error" ? (
+                  <div className="gf-state" role="alert">
+                    <p>预览没能载入。</p>
+                    <div className="gf-state-act">
+                      <button type="button" className="gf-btn" onClick={() => load()}>重试</button>
+                      <a className="gf-btn" href={file.url} download={file.name}>下载文件</a>
+                    </div>
+                  </div>
+                ) : (
+                  <div className="gf-state" role="status">正在载入预览…</div>
+                )}
+              </div>
+            ) : (
+              <div className="gf-db gf-db-frame">
+                {/* Keys pressed inside the iframe never reach this page, so Tab out of it is caught here and kept in the drawer. */}
+                <span tabIndex={0} className="gf-sentinel" data-gf-sentinel="before" onFocus={fromBefore} />
+                <iframe ref={frameRef} className="gf-frame" {...frame} />
+                <span tabIndex={0} className="gf-sentinel" data-gf-sentinel="after" onFocus={fromAfter} />
+              </div>
+            )}
+            <p className="gf-hint">Esc 关闭</p>
+          </aside>
+        </div>,
+        document.body,
+      )
+    : null;
+
+  return (
+    <>
+      <a
+        ref={trigger}
+        href={file.preview === "md" && file.src ? file.src : file.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="gf-btn gf-preview"
+        data-compact={compact ? "true" : undefined}
+        onClick={openDrawer}
+        aria-haspopup="dialog"
+        aria-label={`预览 ${file.name}`}
+      >
+        <ActionGlyph name="eye" />
+        <span className="gf-lb">预览</span>
+      </a>
+      {drawer}
+    </>
+  );
+}

package/app/components/garden/GardenBlock.tsx

@@ -14,6 +14,7 @@ import {
   GardenTimeline,
   GardenUnknown,
 } from "./blocks";
+import { GardenFile } from "./GardenFile";
 
 export function GardenBlock({ dataPayload }: { dataPayload?: string }) {
   const block = readGardenPayload(dataPayload);
@@ -39,6 +40,9 @@ export function GardenBlock({ dataPayload }: { dataPayload?: string }) {
       return <GardenHtml props={props}>{String(block.children ?? "")}</GardenHtml>;
     case "interactive":
       return <GardenInteractive block={{ id: block.id, props, children: block.children }} />;
+    case "file":
+      // Post bodies render file cards on the server (MarkdownArticle); this path has no Markdown preview.
+      return <GardenFile props={props} />;
     default:
       return <GardenUnknown name={String(block.name)} />;
   }

package/app/components/garden/GardenFile.tsx

@@ -0,0 +1,69 @@
+// Server component: the card for `garden file`. Only the 预览 control is a client island.
+import { blockFiles, fileMeta } from "../../../ui/garden/file-block.mjs";
+import { ActionGlyph, FileGlyph, safeFileHref } from "./file-icons";
+import { FilePreview, type PreviewFile } from "./FilePreview";
+
+type FileEntry = {
+  name?: string;
+  title?: string;
+  note?: string;
+  url?: string;
+  format?: string;
+  size?: number;
+  icon?: string;
+  remote?: boolean;
+  preview?: string;
+  /** Markdown: the prerendered preview's address (fetched when the preview opens). */
+  previewSrc?: string;
+};
+
+const PREVIEWS = new Set(["md", "html", "pdf"]);
+
+export function GardenFile({ props }: { props: Record<string, unknown> }) {
+  const block = blockFiles(props) as { layout?: string; title?: string; files: FileEntry[] };
+  const files = block.files.filter((file) => safeFileHref(file.url));
+  if (!files.length) return null;
+  const group = block.layout === "group";
+  return (
+    <div className={group ? "gf group" : "gf single"} data-garden-file="">
+      {group && block.title ? <div className="gf-title">{block.title}</div> : null}
+      {files.map((file, index) => {
+        const href = safeFileHref(file.url);
+        const name = file.name || file.title || "文件";
+        const title = file.title || name;
+        const meta = fileMeta(file);
+        const previewSrc = file.preview === "md" ? safeFileHref(file.previewSrc) : "";
+        const preview = !file.remote && PREVIEWS.has(file.preview ?? "") && (file.preview !== "md" || previewSrc) ? (file.preview as PreviewFile["preview"]) : null;
+        const previewFile: PreviewFile | null = preview ? { title, name, meta, icon: file.icon ?? "file", url: href, preview, ...(previewSrc ? { src: previewSrc } : {}) } : null;
+        return (
+          <div className="gf-row" key={`${href}-${index}`} data-remote={file.remote ? "true" : undefined}>
+            <span className="gf-ico" aria-hidden="true"><FileGlyph kind={file.icon} /></span>
+            <div className="gf-main">
+              <div className="gf-name" title={title}>{title}</div>
+              {file.note ? <div className="gf-desc">{file.note}</div> : null}
+              {meta ? <div className="gf-meta">{meta}</div> : null}
+            </div>
+            <div className="gf-act">
+              {previewFile ? <FilePreview file={previewFile} compact={group} /> : null}
+              {file.remote ? (
+                <a className="gf-btn icon" href={href} target="_blank" rel="noopener noreferrer" aria-label={`在新标签页打开 ${name}`} title="在新标签页打开">
+                  <ActionGlyph name="external" />
+                </a>
+              ) : null}
+              {group ? (
+                <a className="gf-btn icon" href={href} download={file.remote ? undefined : name} aria-label={`下载 ${name}`} title="下载">
+                  <ActionGlyph name="download" />
+                </a>
+              ) : (
+                <a className="gf-btn pri" href={href} download={file.remote ? undefined : name} aria-label={`下载 ${name}`}>
+                  <ActionGlyph name="download" />
+                  <span className="gf-lb">下载</span>
+                </a>
+              )}
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}