hd-garden 0.5.13 → 0.5.15

package/ui/garden/catalog.mjs

@@ -4,7 +4,7 @@
  * Names describe what the reader sees. English only.
  */
 
-export const GARDEN_NAMES = ["card", "stat", "compare", "timeline", "chart", "figure", "html", "interactive"];
+export const GARDEN_NAMES = ["card", "stat", "compare", "timeline", "chart", "figure", "html", "interactive", "file"];
 
 export const LEGACY_FENCES = {
   embed: { name: "card", suggestion: "`embed` 已改为 `garden card`" },
@@ -132,6 +132,20 @@ intent: |
 \`\`\``,
     triggers: ["ginteractive"],
   },
+  file: {
+    label: "文件",
+    when: "给读者一份可以下载的文件：规格包、PDF、示例代码。Markdown、HTML、PDF 还能在页面里预览。",
+    whenNot: "只是引用一个网页时用 card；要在正文里直接展示的图表或页面用 html。",
+    keys: ["src", "title", "note", "files"],
+    itemKeys: ["src", "title", "note"],
+    // Written by the build in place of the authored keys; never by hand.
+    builtKeys: ["resolved"],
+    example: `\`\`\`garden file
+src: ./post-name/spec.zip
+note: 一句话说明里面有什么
+\`\`\``,
+    triggers: ["gfile"],
+  },
 };
 
 export const IDEA = {

package/ui/garden/check.mjs

@@ -3,6 +3,7 @@ import { isProseSteps, isTrivialInteractive } from "./enhance.mjs";
 import { blanksBetween, classifyFence, isFullCodeFence, scanFences } from "./parse.mjs";
 import { splitTitle } from "./title.mjs";
 import { splitCompareLine } from "./compare-line.mjs";
+import { readFileProps } from "./file-block.mjs";
 
 const COMPARE_LIMIT = 60;
 
@@ -82,6 +83,17 @@ export function checkGardenMarkdown(markdown, { draft = false, title = "", title
       push(fence.line, "garden-yaml", block.error.message, allowed.length ? `可用的键：${allowed.join("、")}` : "检查缩进和冒号。");
       return;
     }
+    if (block.name === "file") {
+      if (block.props.resolved !== undefined) {
+        push(fence.line, "garden-file", "resolved 由构建生成，不要手写。", "删掉 resolved，只写 src、title、note 或 files。");
+        return;
+      }
+      const { errors } = readFileProps(block.props);
+      if (errors.length) {
+        push(fence.line, "garden-file", errors.join("；"), "单个文件写 src（可加 title、note）；一组文件写 files 列表，每项一个 src。");
+      }
+      return;
+    }
     if (block.name === "compare" && compareTooLong(block.props)) {
       push(fence.line, "compare-long", "对比格超过约 60 字。", "这一格改回原文的列表或段落。");
     }

package/ui/garden/file-block.mjs

@@ -0,0 +1,232 @@
+/**
+ * `garden file`: downloadable files in a post.
+ *
+ * Authors write a short YAML fence:
+ *
+ *   src: ./post-name/spec.zip        one file
+ *   title: 规格包                     optional, defaults to the file name
+ *   note: 一句话说明                   optional
+ *
+ * or a group:
+ *
+ *   title: 规格文档                    optional
+ *   files:
+ *     - src: ./post-name/01-prd.md
+ *       note: 产品定位与验收标准
+ *
+ * The build resolves every `src` next to the Markdown file, copies repo files
+ * to the public folder and replaces the fence with `resolved:` data (format,
+ * size, preview kind, public URL, and for Markdown the source to render). The
+ * page never parses Markdown in the browser.
+ *
+ * Everything here is plain data work shared by the build, `garden check`, the
+ * page and the tests.
+ */
+/** Repo files above this size get a `garden check` warning suggesting OSS. */
+export const LARGE_FILE_BYTES = 5 * 1024 * 1024;
+
+export const FILE_KEYS = ["src", "title", "note", "files"];
+export const FILE_ITEM_KEYS = ["src", "title", "note"];
+
+const FORMATS = {
+  md: { label: "Markdown", preview: "md", icon: "doc" },
+  markdown: { label: "Markdown", preview: "md", icon: "doc" },
+  html: { label: "HTML", preview: "html", icon: "code" },
+  htm: { label: "HTML", preview: "html", icon: "code" },
+  pdf: { label: "PDF", preview: "pdf", icon: "doc" },
+  zip: { label: "ZIP", preview: "", icon: "archive" },
+  gz: { label: "GZ", preview: "", icon: "archive" },
+  tgz: { label: "TGZ", preview: "", icon: "archive" },
+  "7z": { label: "7Z", preview: "", icon: "archive" },
+  rar: { label: "RAR", preview: "", icon: "archive" },
+  tar: { label: "TAR", preview: "", icon: "archive" },
+};
+
+/**
+ * HTML comments blanked out, line breaks kept, so fences inside a comment (the
+ * component cheat sheet in a new draft) are not mistaken for real blocks.
+ */
+export function maskHtmlComments(markdown) {
+  return String(markdown ?? "").replace(/<!--[\s\S]*?-->/gu, (comment) => comment.replace(/[^\n]/gu, " "));
+}
+
+/** Extension of a path or URL, lower case, without the dot. */
+export function fileExtension(src) {
+  const clean = String(src ?? "").split(/[?#]/u, 1)[0];
+  const base = clean.split("/").pop() ?? "";
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+
+/** File name shown on the card: the last path segment, decoded. */
+export function fileName(src) {
+  const clean = String(src ?? "").split(/[?#]/u, 1)[0].replace(/\/+$/u, "");
+  const base = clean.split("/").pop() ?? "";
+  try {
+    return decodeURIComponent(base);
+  } catch {
+    return base;
+  }
+}
+
+/** Format label: Markdown, HTML, PDF, ZIP, or the extension in capitals. */
+export function formatLabel(src) {
+  const ext = fileExtension(src);
+  return FORMATS[ext]?.label ?? (ext ? ext.toUpperCase() : "文件");
+}
+
+/** Icon family for the card: doc, code, archive or file. */
+export function fileIcon(src) {
+  return FORMATS[fileExtension(src)]?.icon ?? "file";
+}
+
+export const isRemoteSrc = (src) => /^https?:\/\//iu.test(String(src ?? "").trim());
+
+/**
+ * How the drawer previews a file: "md", "html", "pdf", or "" for download only.
+ * Remote files have no preview in this version.
+ */
+export function previewKind(src, { remote = isRemoteSrc(src) } = {}) {
+  if (remote) return "";
+  return FORMATS[fileExtension(src)]?.preview ?? "";
+}
+
+/**
+ * Sandbox for an HTML preview. Scripts may run so prototypes work, but the
+ * page never gets the site's origin: no allow-same-origin.
+ */
+export const HTML_PREVIEW_SANDBOX = "allow-scripts allow-popups allow-forms";
+
+/**
+ * Attributes of the drawer's iframe, or null for a Markdown preview (rendered
+ * on the server, no frame). HTML gets the sandbox; PDF gets none, because the
+ * browser's PDF viewer does not run inside a sandboxed frame.
+ */
+export function previewFrameProps(file) {
+  const kind = file?.preview;
+  if (kind !== "html" && kind !== "pdf") return null;
+  const props = { src: String(file.url ?? ""), title: `预览 ${file.name ?? ""}`.trim(), referrerPolicy: "no-referrer" };
+  return kind === "html" ? { ...props, sandbox: HTML_PREVIEW_SANDBOX } : props;
+}
+
+/** Only web and site paths become links; anything else (javascript:, data:, //host) is dropped. */
+export function safeFileHref(url) {
+  const value = typeof url === "string" ? url.trim() : "";
+  if (/^https?:\/\//iu.test(value)) return value;
+  if (/^[a-z][a-z\d+.-]*:/iu.test(value) || value.startsWith("//")) return "";
+  return value;
+}
+
+/** 12 KB, 1.4 MB: one decimal below 10, whole numbers above. */
+export function formatSize(bytes) {
+  const value = Number(bytes);
+  if (!Number.isFinite(value) || value < 0) return "";
+  if (value < 1024) return `${Math.round(value)} B`;
+  const units = ["KB", "MB", "GB"];
+  let size = value / 1024;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit += 1;
+  }
+  const text = size < 10 ? size.toFixed(1).replace(/\.0$/u, "") : String(Math.round(size));
+  return `${text} ${units[unit]}`;
+}
+
+/** 「Markdown · 12 KB」, or just the format when the size is unknown. */
+export function fileMeta(file) {
+  const size = formatSize(file?.size);
+  return [file?.format, size].filter(Boolean).join(" · ");
+}
+
+const text = (value) => (typeof value === "string" ? value.trim() : value === undefined || value === null ? "" : String(value).trim());
+
+/**
+ * Validates authored props. Returns `{ layout, title, files, errors }` where
+ * `layout` is "single" for one `src`, "group" for a `files` list.
+ */
+export function readFileProps(props) {
+  const errors = [];
+  const data = props && typeof props === "object" && !Array.isArray(props) ? props : {};
+  const item = (raw, where) => {
+    if (typeof raw === "string") return { src: raw.trim(), title: "", note: "" };
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      errors.push(`${where} 要写成带 src 的一项`);
+      return null;
+    }
+    const unknown = Object.keys(raw).filter((key) => !FILE_ITEM_KEYS.includes(key));
+    if (unknown.length) errors.push(`${where} 不支持的键：${unknown.join("、")}`);
+    const src = text(raw.src);
+    if (!src) errors.push(`${where} 缺少 src`);
+    return { src, title: text(raw.title), note: text(raw.note) };
+  };
+  if (data.files !== undefined) {
+    if (data.src !== undefined || data.note !== undefined) errors.push("files 和 src / note 不能同时写：一组文件的说明写在每一项里");
+    if (!Array.isArray(data.files) || !data.files.length) {
+      errors.push("files 要写成至少一项的列表");
+      return { layout: "group", title: text(data.title), files: [], errors };
+    }
+    const files = data.files.map((raw, index) => item(raw, `files 第 ${index + 1} 项`)).filter(Boolean);
+    return { layout: "group", title: text(data.title), files, errors };
+  }
+  const single = item({ src: data.src, title: data.title, note: data.note }, "文件");
+  return { layout: "single", title: "", files: single ? [single] : [], errors };
+}
+
+/** Files of a built or authored block, whichever the fence holds. */
+export function blockFiles(props) {
+  if (props?.resolved && Array.isArray(props.resolved.files)) return props.resolved;
+  const read = readFileProps(props);
+  return {
+    layout: read.layout,
+    title: read.title,
+    files: read.files.map((file) => ({
+      ...file,
+      name: fileName(file.src),
+      title: file.title || fileName(file.src),
+      url: file.src,
+      format: formatLabel(file.src),
+      icon: fileIcon(file.src),
+      remote: isRemoteSrc(file.src),
+      preview: "",
+    })),
+  };
+}
+
+/** Words a reader sees on the card: group title, file titles and notes. */
+export function fileSearchText(props) {
+  const block = blockFiles(props);
+  return [block.title, ...block.files.flatMap((file) => [file.title || file.name, file.note])]
+    .filter(Boolean)
+    .join(" ");
+}
+
+const absolute = (url, siteUrl) => {
+  if (!siteUrl || /^[a-z][a-z\d+.-]*:/iu.test(url)) return url;
+  try {
+    return new URL(url, `${siteUrl.replace(/\/+$/u, "")}/`).toString();
+  } catch {
+    return url;
+  }
+};
+
+// Plain text inside a Markdown link: one line, every character that could start markup escaped.
+const mdText = (value) => String(value ?? "").replace(/\s+/gu, " ").trim().replace(/([\\[\]()*_`<>!~|])/gu, "\\$1");
+
+/** RSS and distribution: a plain list of download links. */
+export function fileFeedMarkdown(props, { siteUrl = "" } = {}) {
+  const block = blockFiles(props);
+  const lines = block.files.map((file) => {
+    const meta = fileMeta(file);
+    const note = file.note ? `：${mdText(file.note)}` : "";
+    const href = absolute(file.url, siteUrl).replace(/[<>\s]/gu, (char) => encodeURIComponent(char));
+    return `- [${mdText(file.title || file.name)}](<${href}>)${meta ? `（${meta}）` : ""}${note}`;
+  });
+  return [block.title ? `**${mdText(block.title)}**\n` : "", ...lines].filter(Boolean).join("\n");
+}
+
+/** The HTML inside a published preview's <main> (what the drawer shows; see scripts/file-preview.mjs). */
+export function previewBody(documentHtml) {
+  const match = /<main class="gf-preview-doc">\n?([\s\S]*?)\n?<\/main>/u.exec(String(documentHtml));
+  return match ? match[1] : "";
+}

package/ui/garden/file-paths.mjs

@@ -0,0 +1,65 @@
+// Node only: where a `garden file` src points on disk. Kept apart from
+// file-block.mjs so the page bundle never pulls in node:path.
+import fs from "node:fs";
+import path from "node:path";
+import { isRemoteSrc, LARGE_FILE_BYTES, formatSize, maskHtmlComments, readFileProps } from "./file-block.mjs";
+import { parseGardenBlock, parseGardenInfo, scanFences } from "./parse.mjs";
+
+/**
+ * Absolute path of a repo file named by a relative `src`, resolved next to the
+ * Markdown file.
+ * Returns `{ path }` or `{ error }` when it leaves the content root.
+ */
+export function resolveRepoFile(src, markdownPath, contentRoot) {
+  const [assetPath] = String(src ?? "").trim().replace(/^<|>$/gu, "").split(/(?=[?#])/u, 1);
+  let decoded = assetPath;
+  try {
+    decoded = decodeURIComponent(assetPath);
+  } catch {
+    // Keep the raw path; a missing file is reported by the caller.
+  }
+  const absolute = path.resolve(path.dirname(markdownPath), decoded);
+  const relative = path.relative(contentRoot, absolute);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return { error: `文件必须放在 content 目录里：${src}` };
+  }
+  return { path: absolute };
+}
+
+/**
+ * `garden check` for the files a post links: every repo file must exist
+ * inside content/, and one above 5 MB gets a warning (Git keeps every version
+ * forever; object storage suits big files). Remote URLs are not fetched here.
+ * `line` is 1-based in `markdown`.
+ */
+export function checkFileSources(markdown, markdownPath, contentRoot) {
+  const diagnostics = [];
+  for (const fence of scanFences(maskHtmlComments(markdown))) {
+    if (parseGardenInfo(fence.info)?.name !== "file") continue;
+    const block = parseGardenBlock(fence.info, fence.body);
+    if (!block || block.error || block.props.resolved !== undefined) continue;
+    for (const file of readFileProps(block.props).files) {
+      if (!file.src || isRemoteSrc(file.src) || file.src.startsWith("/")) continue;
+      const resolved = resolveRepoFile(file.src, markdownPath, contentRoot);
+      if (resolved.error) {
+        diagnostics.push({ line: fence.line, code: "file-outside", severity: "error", message: resolved.error, suggestion: `把文件放进同名目录，例如 ./${path.basename(markdownPath, ".md")}/文件名` });
+        continue;
+      }
+      if (!fs.existsSync(resolved.path) || !fs.statSync(resolved.path).isFile()) {
+        diagnostics.push({ line: fence.line, code: "missing-asset", severity: "error", message: `找不到文件 ${file.src}`, suggestion: "src 相对这篇 Markdown 所在的目录。" });
+        continue;
+      }
+      const size = fs.statSync(resolved.path).size;
+      if (size > LARGE_FILE_BYTES) {
+        diagnostics.push({
+          line: fence.line,
+          code: "file-large",
+          severity: "warning",
+          message: `${file.src} 有 ${formatSize(size)}，超过 5 MB。`,
+          suggestion: "大文件放到对象存储（如阿里云 OSS），src 写完整的 https 地址；Git 会永久保存每个版本。",
+        });
+      }
+    }
+  }
+  return diagnostics;
+}

package/ui/garden/hash-jump.mjs

@@ -0,0 +1,37 @@
+/**
+ * In-page `#` links without a page refetch.
+ *
+ * Following a plain `<a href="#section">` is a fragment navigation: the
+ * browser scrolls, adds a history entry with no state and fires `popstate`.
+ * The router (vinext 0.0.50) treats every `popstate` as a history traversal
+ * and fetches the page's RSC payload again, although only the hash changed.
+ * Next.js itself ignores a popstate without state.
+ *
+ * The guard notes a click on a same-page hash link that nothing else handled,
+ * and swallows the stateless `popstate` that follows it before the router
+ * sees it. On `window`, listeners run in the order they were added, capture
+ * or not, so this has to be added before the router's: it ships as a small
+ * inline script in <head>, which runs before the deferred module scripts.
+ * The click listener sits on `window`, after React's handlers on the
+ * document, so a link that the TOC or a Link already handled is left alone.
+ * Back and forward between real history entries still reach the router.
+ */
+
+/** How long after the click the fragment's popstate may arrive. */
+export const HASH_JUMP_WINDOW_MS = 1000;
+
+export const HASH_JUMP_SCRIPT = `(function(w){var armed=-Infinity;\
+w.addEventListener("click",function(e){\
+if(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)return;\
+var a=e.target&&e.target.closest&&e.target.closest("a[href]");\
+if(!a||a.hasAttribute("download"))return;\
+var t=a.getAttribute("target");if(t&&t!=="_self")return;\
+var h=a.getAttribute("href")||"";if(h.indexOf("#")<0)return;\
+var u,l=w.location;try{u=new URL(h,l.href)}catch(x){return}\
+if(u.origin===l.origin&&u.pathname===l.pathname&&u.search===l.search&&u.hash.length>1)armed=Date.now();\
+});\
+w.addEventListener("popstate",function(e){\
+var on=Date.now()-armed<=${HASH_JUMP_WINDOW_MS};armed=-Infinity;\
+if(on&&e.state==null)e.stopImmediatePropagation();\
+},true);\
+})(window);`;

package/ui/garden/internal-links.mjs

@@ -0,0 +1,113 @@
+/**
+ * In-site links in article bodies.
+ *
+ * `redirects` in site.config.yaml maps old addresses to where pages live now,
+ * and a static export answers the old address with a small meta-refresh page
+ * (scripts/redirects.mjs). A client navigation cannot follow that page: there
+ * is no RSC payload at the old address. So when an article links to an old
+ * address, the rendered link points straight at the new one, keeping the
+ * link's own ?query and #hash.
+ *
+ * `internalRoute` returns the address to give the framework Link, or null to
+ * keep a plain anchor: a link that leaves the site, ends on a file, runs into a
+ * redirect loop or an external target, or lands on no known page.
+ */
+import { clientRoute } from "./same-site.mjs";
+
+/** Valid `{ from, to }` pairs from the config; anything malformed is reported and skipped. */
+export function readRedirects(config = {}, warn = () => {}) {
+  const map = config?.redirects;
+  if (!map) return [];
+  if (typeof map !== "object" || Array.isArray(map)) {
+    warn("redirects 应写成「旧路径: 新地址」的映射，已忽略。");
+    return [];
+  }
+  const pairs = [];
+  for (const [rawFrom, rawTo] of Object.entries(map)) {
+    let from = String(rawFrom).trim();
+    const to = String(rawTo ?? "").trim();
+    try {
+      from = decodeURI(from);
+    } catch {
+      // keep as written
+    }
+    if (!from.startsWith("/") || from.startsWith("//") || from === "/" || /(^|\/)\.\.?(\/|$)/u.test(from) || /[?#]/u.test(from)) {
+      warn(`redirects：旧路径 ${rawFrom} 必须是站内路径（以 / 开头，不带 ?、# 和 ..），已跳过。`);
+      continue;
+    }
+    if (!(to.startsWith("/") && !to.startsWith("//")) && !/^https?:\/\//iu.test(to)) {
+      warn(`redirects：${rawFrom} 的新地址 ${rawTo} 应以 / 开头或是完整网址，已跳过。`);
+      continue;
+    }
+    pairs.push({ from, to });
+  }
+  return pairs;
+}
+
+/** `/columns/<slug>/` → `/columns/#<slug>` for every valid column slug in columns.yaml. */
+export function columnRedirects(columnsConfig = {}) {
+  const columns = Array.isArray(columnsConfig?.columns) ? columnsConfig.columns : [];
+  return columns
+    .map((column) => (column && typeof column.slug === "string" ? column.slug.trim() : ""))
+    .filter((slug) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug))
+    .map((slug) => ({ from: `/columns/${slug}/`, to: `/columns/#${slug}` }));
+}
+
+/** One key per page address: decoded, without a trailing slash (`/` stays `/`). */
+export function routeKey(pathname) {
+  let value = String(pathname ?? "");
+  try {
+    value = decodeURI(value);
+  } catch {
+    // keep as written
+  }
+  return value.length > 1 ? value.replace(/\/+$/u, "") || "/" : value;
+}
+
+const splitHref = (href) => {
+  const hashAt = href.indexOf("#");
+  const beforeHash = hashAt < 0 ? href : href.slice(0, hashAt);
+  const hash = hashAt < 0 ? "" : href.slice(hashAt);
+  const queryAt = beforeHash.indexOf("?");
+  return { pathname: queryAt < 0 ? beforeHash : beforeHash.slice(0, queryAt), search: queryAt < 0 ? "" : beforeHash.slice(queryAt), hash };
+};
+
+/**
+ * Build the resolver once per render.
+ * - redirects: `{ from, to }` pairs (readRedirects + columnRedirects).
+ * - routes: every page address the site builds, without the base path.
+ * - basePath: NEXT_PUBLIC_BASE_PATH; Link adds it back.
+ * - format: shapes the route it returns (the app passes siteHref, which adds the trailing slash).
+ */
+export function internalLinkResolver({ redirects = [], routes = [], basePath = "", format = (href) => href } = {}) {
+  const moved = new Map();
+  for (const { from, to } of redirects) if (!moved.has(routeKey(from))) moved.set(routeKey(from), to);
+  const pages = new Set([...routes].map(routeKey));
+  const base = String(basePath ?? "").trim().replace(/\/+$/u, "");
+  return function internalRoute(href) {
+    if (typeof href !== "string") return null;
+    let value = href.trim();
+    if (!value.startsWith("/") || value.startsWith("//")) return null;
+    if (base) {
+      if (value !== base && !value.startsWith(`${base}/`) && !value.startsWith(`${base}?`) && !value.startsWith(`${base}#`)) return null;
+      value = value.slice(base.length) || "/";
+      if (!value.startsWith("/")) value = `/${value}`;
+    }
+    const own = splitHref(value);
+    let target = own;
+    const seen = new Set();
+    while (moved.has(routeKey(target.pathname))) {
+      const key = routeKey(target.pathname);
+      if (seen.has(key) || seen.size > 16) return null;
+      seen.add(key);
+      const to = moved.get(key);
+      if (!to.startsWith("/") || to.startsWith("//")) return null;
+      const next = splitHref(to);
+      // The link's own ?query and #hash win; otherwise the redirect target's.
+      target = { pathname: next.pathname || "/", search: own.search || next.search, hash: own.hash || next.hash };
+    }
+    if (!pages.has(routeKey(target.pathname))) return null;
+    const route = clientRoute(`${target.pathname}${target.search}${target.hash}`);
+    return route ? format(route) : route;
+  };
+}

package/ui/garden/markdown-syntax.mjs

@@ -0,0 +1,12 @@
+import remarkBreaks from "remark-breaks";
+import remarkCjkFriendly from "remark-cjk-friendly";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+
+/**
+ * The Markdown syntax every post is read with: GFM, CJK-friendly emphasis,
+ * hard line breaks and math. Posts add remarkGarden on top
+ * (app/lib/markdown-plugins.ts); a previewed Markdown file uses this list as
+ * is (scripts/file-preview.mjs), so both read the same Markdown the same way.
+ */
+export const markdownSyntaxPlugins = [remarkGfm, remarkCjkFriendly, remarkBreaks, remarkMath];

package/ui/garden/parse.mjs

@@ -137,7 +137,7 @@ export function parseGardenBlock(info, body) {
       error: { code: "garden-name", message: `未知名字 ${header.name}` },
     };
   }
-  const unknown = Object.keys(props).filter((key) => key !== "id" && !spec.keys.includes(key));
+  const unknown = Object.keys(props).filter((key) => key !== "id" && !spec.keys.includes(key) && !spec.builtKeys?.includes(key));
   if (unknown.length) {
     return {
       name: header.name,

package/ui/garden/same-site.mjs

@@ -61,3 +61,30 @@ export function articleLink(href, sameSite) {
   if (local !== null) return { href: local, external: false };
   return { href, external: /^(https?:)?\/\//iu.test(href) };
 }
+
+/** Static files the site serves next to its pages; these always load as files. */
+const FILE_PREFIXES = ["/api/", "/assets/", "/images/", "/media/", "/link-assets/", "/_next/", "/fonts/"];
+
+/**
+ * The route to hand to the framework Link for an in-article link, or null to
+ * keep a plain anchor. Only a root-relative page address qualifies: no
+ * protocol or host, not just a hash, no file extension in the last segment,
+ * none of the static file folders. Link adds the base path itself, so it is
+ * taken off here; a path outside the base path stays a plain anchor.
+ */
+export function clientRoute(href, basePath = "") {
+  if (typeof href !== "string") return null;
+  const value = href.trim();
+  if (!value.startsWith("/") || value.startsWith("//")) return null;
+  const base = normalizeBase(basePath);
+  const [pathname] = value.split(/[?#]/u);
+  let route = pathname;
+  if (base) {
+    if (route !== base && !route.startsWith(`${base}/`)) return null;
+    route = route.slice(base.length) || "/";
+  }
+  if (FILE_PREFIXES.some((prefix) => route.startsWith(prefix) || `${route}/` === prefix)) return null;
+  const last = route.split("/").filter(Boolean).at(-1) ?? "";
+  if (/\.[a-z0-9]{1,8}$/iu.test(last)) return null;
+  return `${route}${value.slice(pathname.length)}`;
+}

package/ui/garden/site-href.mjs

@@ -0,0 +1,62 @@
+/**
+ * Whether page addresses end with a slash: Next's `trailingSlash`.
+ *
+ * A static export always uses it: every page is a folder (`/blog/post/`) and
+ * the host answers `/blog/post` with a 301 first. A server build uses it only
+ * with TRAILING_SLASH=1; without it the server answers `/blog/post/` with a
+ * 308 to `/blog/post`, so links must not carry the slash there.
+ * next.config.ts and the generated siteLinks both read this.
+ */
+export function trailingSlashEnabled(env = process.env) {
+  return env.STATIC_EXPORT === "1" || env.TRAILING_SLASH === "1";
+}
+
+/**
+ * The one place that shapes an address inside the site.
+ *
+ * With `trailing` (the default) every page path ends with a slash; without it
+ * the slash is dropped (the root stays `/`). `?query` and `#hash` come after
+ * the path either way. Files (a last segment with an extension), pure `#hash`
+ * or `?query` links and anything outside the site are left alone.
+ */
+export function withTrailingSlash(href, trailing = true) {
+  if (typeof href !== "string") return href;
+  const value = href.trim();
+  if (!value.startsWith("/") || value.startsWith("//")) return value;
+  const hashAt = value.indexOf("#");
+  const beforeHash = hashAt < 0 ? value : value.slice(0, hashAt);
+  const hash = hashAt < 0 ? "" : value.slice(hashAt);
+  const queryAt = beforeHash.indexOf("?");
+  let pathname = queryAt < 0 ? beforeHash : beforeHash.slice(0, queryAt);
+  const search = queryAt < 0 ? "" : beforeHash.slice(queryAt);
+  const last = pathname.split("/").filter(Boolean).at(-1) ?? "";
+  if (/\.[a-z0-9]{1,8}$/iu.test(last)) return value;
+  if (trailing) {
+    if (!pathname.endsWith("/")) pathname = `${pathname}/`;
+  } else if (pathname.length > 1) {
+    pathname = pathname.replace(/\/+$/u, "") || "/";
+  }
+  return `${pathname}${search}${hash}`;
+}
+
+const decodeAttribute = (value) =>
+  value.replace(/&amp;/gu, "&").replace(/&quot;/gu, '"').replace(/&#x27;|&#39;/gu, "'").replace(/&lt;/gu, "<").replace(/&gt;/gu, ">");
+
+/**
+ * Links in a built page whose site path has the wrong shape for the build:
+ * `<a>` and `<area>` hrefs that start with one `/` and lack the trailing slash
+ * (`trailing`, a static export) or carry one (a server build without it).
+ * Files (an extension in the last segment) and pure #hash links are fine.
+ */
+export function findMisshapenLinks(html, { trailing = true } = {}) {
+  const found = [];
+  for (const match of String(html ?? "").matchAll(/<(?:a|area)\b[^>]*?\shref\s*=\s*(?:"([^"]*)"|'([^']*)')/giu)) {
+    const href = decodeAttribute(match[1] ?? match[2] ?? "").trim();
+    if (!href.startsWith("/") || href.startsWith("//")) continue;
+    if (withTrailingSlash(href, trailing) !== href) found.push(href);
+  }
+  return found;
+}
+
+/** Internal page links without the trailing slash (checks a static export). */
+export const findSlashlessLinks = (html) => findMisshapenLinks(html, { trailing: true });

package/ui/garden/site-nav.mjs

@@ -0,0 +1,25 @@
+/**
+ * The header's site navigation. Hrefs carry the trailing slash: a static
+ * export serves these pages at /blog/ and so on, and the host answers /blog
+ * with a 301 first (new tab, no JavaScript, crawlers).
+ */
+export const SITE_NAV = [
+  { href: "/blog/", label: "文章" },
+  { href: "/thoughts/", label: "随想" },
+  { href: "/columns/", label: "专栏" },
+  { href: "/tags/", label: "标签" },
+  { href: "/about/", label: "关于" },
+];
+
+const trim = (value) => (value.length > 1 ? value.replace(/\/+$/u, "") : value);
+
+/**
+ * Whether a nav item is the current section. The pathname may come with or
+ * without the trailing slash; articles count as 文章 (/blog/…, /a2/…).
+ */
+export function isCurrentNav(pathname, href) {
+  const path = trim(pathname || "/");
+  const section = trim(href);
+  if (section === "/blog") return path === "/blog" || path.startsWith("/blog/") || path.startsWith("/a2/");
+  return path === section || path.startsWith(`${section}/`);
+}

package/ui/garden/snippets.mjs

@@ -15,8 +15,8 @@ export function vscodeSnippets() {
   const snippets = {
     "Garden 块": {
       prefix: "garden",
-      body: ["```garden ${1|idea,card,stat,compare,timeline,chart,figure,html,interactive|}", "$0", "```"],
-      description: "选择 Garden 块：想法 / card / stat / compare / timeline / chart / figure / html / interactive",
+      body: [`\`\`\`garden \${1|${["idea", ...GARDEN_NAMES].join(",")}|}`, "$0", "```"],
+      description: `选择 Garden 块：想法 / ${GARDEN_NAMES.join(" / ")}`,
     },
   };
   for (const trigger of IDEA.triggers) {