hd-garden 0.8.0 → 0.8.2

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", "file"];
+export const GARDEN_NAMES = ["card", "stat", "compare", "timeline", "chart", "figure", "html", "interactive", "file", "relations", "list", "choice"];
 
 export const LEGACY_FENCES = {
   embed: { name: "card", suggestion: "`embed` 已改为 `garden card`" },
@@ -19,7 +19,8 @@ export const CATALOG = {
     label: "资源卡",
     when: "一篇论文、一个仓库或一本书，读者需要标题、链接和一句说明。",
     whenNot: "正文里已经有这句话时，不要再包一张卡。",
-    keys: ["url", "title", "description", "image", "alt", "points", "meta", "text", "source", "site", "items"],
+    keys: ["url", "title", "description", "image", "alt", "points", "meta", "text", "source", "site", "items", "takeaway", "cards"],
+    itemKeys: ["url", "title", "description", "image", "alt", "meta", "text", "source", "takeaway"],
     example: `\`\`\`garden card
 url: https://arxiv.org/abs/2309.06180
 title: PagedAttention
@@ -46,7 +47,7 @@ items:
     when: "两三件东西并排，每格约 60 字以内。原文是「X：Y」列表时，每格写成一行带引号的「X：Y」。",
     whenNot: "任何一格超过约 60 字时，用原文的列表，不要并排。",
     keys: ["items"],
-    itemKeys: ["title", "text"],
+    itemKeys: ["title", "text", "verdict"],
     example: `\`\`\`garden compare
 items:
   - title: 自旋锁
@@ -146,6 +147,77 @@ note: 一句话说明里面有什么
 \`\`\``,
     triggers: ["gfile"],
   },
+  relations: {
+    label: "关系图",
+    when: "三到六个关键要素，读者需要看清谁影响谁、哪些是双向的；首尾相接的循环也用它，把每一步写成一条 link。",
+    whenNot: "要素更多、有分支或先后顺序时，用 ```mermaid 流程图；只走一遍的步骤用 garden list。",
+    keys: ["title", "items", "center", "links", "caption"],
+    itemKeys: ["title", "text"],
+    linkKeys: ["from", "to", "style", "direction", "label"],
+    example: `\`\`\`garden relations
+items:
+  - title: 观察
+    text: 记下发生了什么
+  - title: 假设
+    text: 猜一个原因
+  - title: 实验
+    text: 只改一个变量
+  - title: 复盘
+    text: 留下能复用的结论
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 4
+    to: 2
+    style: dashed
+    label: 改写
+caption: 复盘的结论会改写下一轮的假设。
+\`\`\``,
+    triggers: ["grel"],
+  },
+  list: {
+    label: "图标列表",
+    when: "几条并列的行为、信号或做法，每条配一个线条图标；带标题时每条可以写几段说明。",
+    whenNot: "条目之间有先后顺序或要编号时，用普通有序列表。",
+    keys: ["title", "items", "caption"],
+    itemKeys: ["icon", "title", "text"],
+    example: `\`\`\`garden list
+items:
+  - icon: search
+    text: 搜索「降噪耳机」
+  - icon: eye
+    text: 看了 5 个商品详情
+\`\`\``,
+    triggers: ["glist"],
+  },
+  choice: {
+    label: "选择卡",
+    when: "给读者两三个具体选项让他选一个，每个选项有图标、一个醒目的数字和一句说明。",
+    whenNot: "选项会改变后面的计算结果时，写成想法，编译成 interactive。",
+    keys: ["title", "items", "none", "caption"],
+    itemKeys: ["icon", "value", "text", "label", "reply"],
+    example: `\`\`\`garden choice
+title: 你更倾向哪一种？
+items:
+  - icon: shield
+    value: ¥2,950
+    text: 原装，价格略高
+    label: 更看重可靠
+  - icon: wallet
+    value: ¥2,450
+    text: 换过电池，价格更低
+    label: 更看重价格
+none:
+  label: 都不合适
+\`\`\``,
+    triggers: ["gchoice"],
+  },
 };
 
 export const IDEA = {
@@ -201,7 +273,136 @@ export function suggestName(name) {
   return best;
 }
 
-export function cheatSheet() {
+export const IDEA_EN = {
+  label: "Idea",
+  when: "When you are not sure which component to use yet, write one sentence about what you want the reader to see.",
+  whenNot: "Must be compiled before publishing. Fine to leave in drafts.",
+  example: `\`\`\`garden
+Let the reader see...; show how...
+\`\`\``,
+  triggers: ["gidea"],
+};
+
+export const CATALOG_EXAMPLES_EN = {
+  card: `\`\`\`garden card
+url: https://arxiv.org/abs/2309.06180
+title: PagedAttention
+description: Paged KV cache management in vLLM.
+\`\`\``,
+  stat: `\`\`\`garden stat
+items:
+  - label: Llama-2-13B · 4K context
+    value: 3.2
+    unit: GiB
+    source: https://arxiv.org/abs/2309.06180
+\`\`\``,
+  compare: `\`\`\`garden compare
+items:
+  - title: Spinlock
+    text: Busy-waits when the critical section is tiny; never sleeps.
+  - title: Mutex
+    text: Sleeps under contention to avoid burning CPU cycles.
+\`\`\``,
+  timeline: `\`\`\`garden timeline
+items:
+  - date: 2015
+    title: Concurrent mark
+    text: Pause times drop significantly.
+  - date: 2017
+    title: Stack rescan moved out of STW
+    text: Pauses typically stay under 100 microseconds.
+  - date: 2022
+    title: Soft memory limit
+    text: Runtime adds GOMEMLIMIT.
+\`\`\``,
+  chart: `\`\`\`garden chart
+type: bar
+title: Sample latency
+x: Option
+series:
+  - name: Latency
+    data: [120, 85]
+unit: ms
+\`\`\``,
+  figure: `\`\`\`garden figure
+image: ./figure.svg
+parts:
+  - name: All
+    text: The full diagram.
+  - name: Mark
+    text: This step only marks reachable objects.
+\`\`\``,
+  html: `\`\`\`garden html
+src: ./demo.html
+title: Diagram
+\`\`\``,
+  interactive: `\`\`\`garden interactive #kv-memory
+caption: KV memory scales linearly with both batch size and sequence length.
+intent: |
+  Let the reader adjust batch size and inspect KV memory.
+---
+<State batch={1} />
+\`\`\``,
+  file: `\`\`\`garden file
+src: ./post-name/spec.zip
+note: One-line summary of what is inside
+\`\`\``,
+  relations: `\`\`\`garden relations
+items:
+  - title: Observe
+    text: Note what happened
+  - title: Hypothesize
+    text: Guess one cause
+  - title: Experiment
+    text: Change one variable
+  - title: Review
+    text: Keep a reusable lesson
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 4
+    to: 2
+    style: dashed
+    label: revises
+caption: The review revises the next round's hypothesis.
+\`\`\``,
+  list: `\`\`\`garden list
+items:
+  - icon: search
+    text: Searched for "noise-cancelling headphones"
+  - icon: eye
+    text: Viewed 5 product pages
+\`\`\``,
+  choice: `\`\`\`garden choice
+title: Which would you pick?
+items:
+  - icon: shield
+    value: $415
+    text: Original, a bit pricier
+    label: Reliability first
+  - icon: wallet
+    value: $345
+    text: Battery replaced, cheaper
+    label: Price first
+none:
+  label: Neither fits
+\`\`\``,
+};
+
+export function cheatSheet(lang = "zh") {
+  if (lang === "en") {
+    const blocks = [
+      IDEA_EN.example,
+      ...GARDEN_NAMES.map((name) => CATALOG_EXAMPLES_EN[name] ?? CATALOG[name].example),
+    ];
+    return ["<!-- Component cheat sheet. Copy the block you need and delete this comment.", ...blocks.flatMap((example) => ["", example]), "-->"].join("\n");
+  }
   const blocks = [
     IDEA.example,
     ...GARDEN_NAMES.map((name) => CATALOG[name].example),

package/ui/garden/check.mjs

@@ -24,6 +24,8 @@ function cellText(item) {
 
 function compareTooLong(props) {
   const items = Array.isArray(props?.items) ? props.items : [];
+  // Good/bad verdicts stack one under another, so a longer quote still reads well.
+  if (items.some((item) => item && typeof item === "object" && (item.verdict === "good" || item.verdict === "bad"))) return false;
   return items.some((item) => [...cellText(item).trim()].length > COMPARE_LIMIT);
 }
 
@@ -84,6 +86,10 @@ export function checkGardenMarkdown(markdown, { draft = false, title = "", title
       push(fence.line, "garden-yaml", block.error.message, allowed.length ? `可用的键：${allowed.join("、")}` : "检查缩进和冒号。");
       return;
     }
+    if (block.error?.code === "garden-relations") {
+      push(fence.line, "garden-relations", block.error.message, "要素更多或有分支：```mermaid flowchart；一次走完的步骤：garden list。");
+      return;
+    }
     if (block.name === "file") {
       if (block.props.resolved !== undefined) {
         push(fence.line, "garden-file", "resolved 由构建生成，不要手写。", "删掉 resolved，只写 src、title、note 或 files。");

package/ui/garden/file-block.mjs

@@ -69,10 +69,10 @@ export function fileName(src) {
   }
 }
 
-/** Format label: the extension in capitals (MD, HTML, PDF, ZIP, CSV …), or 文件 when there is none. */
-export function formatLabel(src) {
+/** Format label: the extension in capitals (MD, HTML, PDF, ZIP, CSV …), or 文件 / FILE when there is none. */
+export function formatLabel(src, lang = "zh") {
   const ext = fileExtension(src);
-  return ext ? ext.toUpperCase() : "文件";
+  return ext ? ext.toUpperCase() : lang === "en" ? "FILE" : "文件";
 }
 
 /** Icon family for the card: doc, code, archive or file. */
@@ -102,10 +102,11 @@ export const HTML_PREVIEW_SANDBOX = "allow-scripts allow-popups allow-forms";
  * 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) {
+export function previewFrameProps(file, lang = "zh") {
   const kind = file?.preview;
   if (kind !== "html" && kind !== "pdf") return null;
-  const props = { src: String(file.url ?? ""), title: `预览 ${file.name ?? ""}`.trim(), referrerPolicy: "no-referrer" };
+  const prefix = lang === "en" ? "Preview" : "预览";
+  const props = { src: String(file.url ?? ""), title: `${prefix} ${file.name ?? ""}`.trim(), referrerPolicy: "no-referrer" };
   return kind === "html" ? { ...props, sandbox: HTML_PREVIEW_SANDBOX } : props;
 }
 
@@ -174,7 +175,7 @@ export function readFileProps(props) {
 }
 
 /** Files of a built or authored block, whichever the fence holds. */
-export function blockFiles(props) {
+export function blockFiles(props, lang = "zh") {
   if (props?.resolved && Array.isArray(props.resolved.files)) return props.resolved;
   const read = readFileProps(props);
   return {
@@ -185,7 +186,7 @@ export function blockFiles(props) {
       name: fileName(file.src),
       title: file.title || fileName(file.src),
       url: file.src,
-      format: formatLabel(file.src),
+      format: formatLabel(file.src, lang),
       icon: fileIcon(file.src),
       remote: isRemoteSrc(file.src),
       preview: "",

package/ui/garden/html-lang.mjs

@@ -1,10 +1,53 @@
 /**
- * The <html lang> of a page. The root layout is shared by every route and is
+ * The <html lang> of a page, plus 404 language resolution for missing
+ * /garden/en/* routes. The root layout is shared by every route and is
  * rendered once with the site language; the English handbook (/garden/en/)
  * gets lang="en" here: in the worker response and in the static export.
  */
 const EN_HANDBOOK = /(^|\/)garden\/en(\/|$)/u;
 
+/**
+ * Strip a configured basePath (e.g. "/garden-docs-v6") from the front of a
+ * browser pathname. Returns a leading-slash pathname.
+ */
+export function stripConfiguredBasePath(pathname, basePath = "") {
+  const raw = `/${String(pathname ?? "").replace(/^\/+/u, "")}`;
+  const base = String(basePath ?? "").replace(/\/+$/u, "").replace(/^\/+/u, "");
+  if (!base) return raw;
+  const prefix = `/${base}`;
+  if (raw === prefix) return "/";
+  if (raw.startsWith(`${prefix}/`)) return raw.slice(prefix.length);
+  return raw;
+}
+
+/**
+ * Normalize a browser or router pathname to an in-app route by stripping a
+ * configured basePath or a leading deployment prefix before /garden.
+ */
+export function inAppPath(pathname, basePath = "") {
+  if (!pathname) return "/";
+  const stripped = stripConfiguredBasePath(pathname, basePath);
+  const gardenMatch = /^\/[^/]+(\/garden(?:\/.*)?)$/u.exec(stripped);
+  if (gardenMatch) return gardenMatch[1];
+  return stripped;
+}
+
+/** True when pathname (with or without a basePath) is under /garden. */
+export function isHandbookPath(pathname, basePath = "") {
+  const p = inAppPath(pathname, basePath);
+  return p === "/garden" || p.startsWith("/garden/");
+}
+
+/**
+ * Pick the 404 page language ("en" or "zh") from a pathname after stripping
+ * the configured basePath. If the stripped path starts with /garden/en/ (or
+ * equals /garden/en), returns "en"; otherwise returns "zh".
+ */
+export function pickNotFoundLang(pathname, basePath = "") {
+  const stripped = stripConfiguredBasePath(pathname, basePath);
+  return /^\/garden\/en(\/|$)/u.test(stripped) ? "en" : "zh";
+}
+
 /** "en" for an English handbook path (with or without a basePath in front), else null. */
 export function handbookHtmlLang(pathname) {
   return EN_HANDBOOK.test(String(pathname ?? "").replace(/^\/+/u, "")) ? "en" : null;
@@ -14,3 +57,32 @@ export function handbookHtmlLang(pathname) {
 export function withHtmlLang(html, lang) {
   return String(html).replace(/<html\b([^>]*?)\slang="[^"]*"/u, `<html$1 lang="${lang}"`);
 }
+
+function replaceMetaContent(html, attrName, attrValue, nextContent) {
+  const escapedVal = attrValue.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const forwardRe = new RegExp(`(<meta\\b[^>]*\\b${attrName}="${escapedVal}"[^>]*\\bcontent=")[^"]*(")`, "gu");
+  const reverseRe = new RegExp(`(<meta\\b[^>]*\\bcontent=")[^"]*("[^>]*\\b${attrName}="${escapedVal}")`, "gu");
+  return html.replace(forwardRe, `$1${nextContent}$2`).replace(reverseRe, `$1${nextContent}$2`);
+}
+
+/**
+ * Updates <html lang="en"> and <head> metadata on a server-rendered English 404
+ * response so the initial HTTP response has English <title> and <meta> tags.
+ */
+export function withEnglishNotFoundHead(html) {
+  let out = withHtmlLang(String(html), "en");
+  const titleMatch = /<title>([^<]*)<\/title>/u.exec(out);
+  const siteName = titleMatch ? titleMatch[1].split(" · ").at(-1)?.trim() || "Garden" : "Garden";
+  const enTitle = `Page not found · ${siteName}`;
+  const enDesc = "The address may be wrong, or the page has moved.";
+
+  out = out.replace(/<title>[^<]*<\/title>/u, `<title>${enTitle}</title>`);
+  out = replaceMetaContent(out, "name", "description", enDesc);
+  out = replaceMetaContent(out, "property", "og:title", enTitle);
+  out = replaceMetaContent(out, "property", "og:description", enDesc);
+  out = replaceMetaContent(out, "property", "og:locale", "en_US");
+  out = replaceMetaContent(out, "property", "og:image:alt", enTitle);
+  out = replaceMetaContent(out, "name", "twitter:title", enTitle);
+  out = replaceMetaContent(out, "name", "twitter:description", enDesc);
+  return out;
+}

package/ui/garden/markdown-links.mjs

@@ -51,7 +51,7 @@ function mapInline(text, visit) {
 // Inline links read as CommonMark reads them (ui/garden/markdown-destination.mjs):
 // `[t](<https://e.com/a (1)>)` and `[t](https://e.com/Trie_(x))` are whole addresses.
 // Groups: 1 `!`, 3 or 4 the address, 6 `{card}`.
-const LINK = new RegExp(`${INLINE_LINK_SOURCE}(\\{card\\})?`, "giu");
+const LINK = new RegExp(`${INLINE_LINK_SOURCE}(\\{card\\}|\\{source\\})?`, "giu");
 const linkUrl = (match) => match[3] ?? match[4];
 const isWebUrl = (url) => /^https?:\/\//iu.test(url);
 const AUTOLINK = /<(https?:\/\/[^\s>]+)>/giu;
@@ -62,7 +62,7 @@ export function markdownLinks(markdown) {
   const links = [];
   mapOutsideCode(markdown, (text) => {
     for (const match of text.matchAll(LINK)) {
-      if (match[1] !== "!" && isWebUrl(linkUrl(match))) links.push({ url: linkUrl(match), card: Boolean(match[6]) });
+      if (match[1] !== "!" && isWebUrl(linkUrl(match))) links.push({ url: linkUrl(match), card: match[6] === CARD_MARKER });
     }
     const rest = text.replace(LINK, " ");
     for (const match of rest.matchAll(AUTOLINK)) links.push({ url: match[1], card: false });
@@ -74,14 +74,17 @@ export function markdownLinks(markdown) {
 
 /** The marker that asks for a link card: `[text](url){card}`, nothing in between. */
 export const CARD_MARKER = "{card}";
+/** The marker that draws a link as an inline source chip: `[site](url){source}`. */
+export const SOURCE_MARKER = "{source}";
 
 /**
  * The same Markdown without `{card}` markers, for excerpts, RSS and the search
  * index. Markers inside code stay, since there they are literal text.
  */
 export function stripCardMarkers(markdown) {
-  if (!String(markdown ?? "").includes(CARD_MARKER)) return markdown;
-  return mapOutsideCode(markdown, (text) => text.replace(LINK, (...match) => (match[6] && isWebUrl(linkUrl(match)) ? match[0].slice(0, -CARD_MARKER.length) : match[0])));
+  const raw = String(markdown ?? "");
+  if (!raw.includes(CARD_MARKER) && !raw.includes(SOURCE_MARKER)) return markdown;
+  return mapOutsideCode(markdown, (text) => text.replace(LINK, (...match) => (match[6] && isWebUrl(linkUrl(match)) ? match[0].slice(0, -match[6].length) : match[0])));
 }
 
 /** URLs the author asked to show as cards, in order, without repeats. */

package/ui/garden/parse.mjs

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from "yaml";
 import { CATALOG, knownName, legacyOf } from "./catalog.mjs";
+import { relationIndex } from "./relations.mjs";
 
 const FENCE_RE = /^( {0,3})(`{3,}|~{3,})(.*)$/u;
 
@@ -91,6 +92,37 @@ function asObject(value) {
  * An empty name is an idea. Invalid YAML or an unknown name is still returned,
  * with `error` set, so the checker and the renderer share one parse.
  */
+export const RELATIONS_MIN = 3;
+export const RELATIONS_MAX = 6;
+
+function relationsProblem(props) {
+  const items = Array.isArray(props.items) ? props.items : [];
+  if (items.length < RELATIONS_MIN || items.length > RELATIONS_MAX) {
+    return `relations 需要 ${RELATIONS_MIN} 到 ${RELATIONS_MAX} 个要素，现在是 ${items.length} 个。要素更多或有分支时改用 \`\`\`mermaid 流程图；只走一遍的步骤用 garden list。`;
+  }
+  if (props.center != null && relationIndex(props.center, items.map((item) => String(item?.title ?? ""))) < 0) {
+    return "center 要写放在中间的那个要素的序号（1 起）或标题。";
+  }
+  if (props.links == null) return "";
+  if (!Array.isArray(props.links)) return "links 必须是列表。";
+  const titles = items.map((item) => String(item?.title ?? ""));
+  const allowed = CATALOG.relations.linkKeys;
+  for (const [index, link] of props.links.entries()) {
+    const where = `links 第 ${index + 1} 条`;
+    if (!link || typeof link !== "object") return `${where}要写 from 和 to。`;
+    const unknown = Object.keys(link).filter((key) => !allowed.includes(key));
+    if (unknown.length) return `${where}不支持 ${unknown.join("、")}（可用：${allowed.join("、")}）。`;
+    const from = relationIndex(link.from, titles);
+    const to = relationIndex(link.to, titles);
+    if (from < 0 || to < 0) return `${where}的 from/to 要写要素序号（1 起）或标题。`;
+    if (from === to) return `${where}的 from 和 to 是同一个要素。`;
+    if (link.style != null && !["solid", "dashed"].includes(link.style)) return `${where}的 style 只能是 solid 或 dashed。`;
+    if (link.direction != null && !["one", "both"].includes(link.direction)) return `${where}的 direction 只能是 one 或 both。`;
+    if (link.label != null && typeof link.label !== "string") return `${where}的 label 要写一小段文字。`;
+  }
+  return "";
+}
+
 export function parseGardenBlock(info, body) {
   const header = parseGardenInfo(info);
   if (!header) return null;
@@ -148,6 +180,19 @@ export function parseGardenBlock(info, body) {
       error: { code: "garden-yaml", message: `不支持的键 ${unknown.join("、")}`, unknown, allowed: spec.keys },
     };
   }
+  if (header.name === "relations") {
+    const problem = relationsProblem(props);
+    if (problem) {
+      return {
+        name: header.name,
+        props,
+        children,
+        id: header.id ?? props.id ?? null,
+        legacy: Boolean(header.legacy),
+        error: { code: "garden-relations", message: problem },
+      };
+    }
+  }
   return {
     name: header.name,
     props,