hd-garden 0.14.12 → 0.14.13

package/scripts/handbook-diagrams.mjs

@@ -0,0 +1,434 @@
+/**
+ * Generate handbook pages and preview SVGs from ui/garden/diagram-recipes.mjs.
+ * The Typora and VS Code pickers both read that same list.
+ *
+ * Usage:
+ *   node scripts/handbook-diagrams.mjs
+ *   node scripts/handbook-diagrams.mjs --check
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DIAGRAM_RECIPES } from "../ui/garden/diagram-recipes.mjs";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const PREVIEW_DIR = path.join(ROOT, "docs/handbook/components/diagrams/previews");
+const ZH_DIR = path.join(ROOT, "docs/handbook/components/diagrams");
+const EN_DIR = path.join(ROOT, "docs/handbook/en/components/diagrams");
+const ZH_INDEX = path.join(ROOT, "docs/handbook/components/diagrams.md");
+const EN_INDEX = path.join(ROOT, "docs/handbook/en/components/diagrams.md");
+const STALE_FILES = [
+  path.join(ZH_DIR, "index.md"),
+  path.join(EN_DIR, "index.md"),
+];
+const MARKER = "<!-- Generated by scripts/handbook-diagrams.mjs. Do not edit by hand. -->\n";
+
+/** English copy for the handbook only. The picker still inserts the Chinese brief. */
+const EN = {
+  "columns-join": {
+    label: "Join diagram",
+    hint: "Use this to show how two sides connect through a middle item",
+    when: "Two sides connect through a middle item",
+    whenNot: "If there is no middle connection, do not force one",
+    routeHint: "First name the two sides, how the middle item joins them, and which block is the focus",
+  },
+  "fan-out": {
+    label: "Fan-out diagram",
+    hint: "Use this to show a first stop that then branches to several places at once",
+    when: "A first stop, then several places at once",
+    whenNot: "If there is no real first stop and then a branch, do not draw a fan-out",
+    routeHint: "First say who reaches whom, then which places are reached at once, and which place is the focus",
+  },
+  layers: {
+    label: "Layer diagram",
+    hint: "Use this to show top-down layers that do not have to be walked in order",
+    when: "Top-down layers",
+    whenNot: "Layers are not automatically a flow that must be walked in order",
+    routeHint: "Name each layer, say which layers are the focus, and whether every request follows this order",
+  },
+  facets: {
+    label: "Aspect diagram",
+    hint: "Use this to show several aspects of one thing, with no required order",
+    when: "Several aspects of one thing, with no required order",
+    whenNot: "If there is no order, do not draw a flow. If you are not comparing options under the same conditions, do not use a comparison diagram",
+    routeHint: "List a short name and a note for each aspect, and say whether the blocks have a strict order",
+  },
+  "two-row": {
+    label: "Two-row contrast",
+    hint: "Use this to contrast a background process with the process you want to emphasize, on two rows",
+    when: "The upper row is background; the lower row is the process you want to explain",
+    whenNot: "If you are not contrasting two processes, or you are comparing options under the same conditions, do not use this two-row layout",
+    routeHint: "Name the stages of the background process above and the focus process below, and say which row is the focus",
+  },
+  "icon-rail": {
+    label: "Illustrated list",
+    hint: "Use this to explain independent items one by one",
+    when: "Independent notes, each with an icon, a title, and body text",
+    whenNot: "If the items have no order dependence, do not draw a flow, and do not write them as a checklist to follow",
+    routeHint: "Lead each independent note with an icon, and keep the title and body together. This is not a flow, so do not add sequence arrows",
+  },
+  sequence: {
+    label: "Flow diagram",
+    hint: "Use this to show the order in which something is done",
+    when: "The order in which something is done",
+    whenNot: "Do not add arrows to unordered items, and do not shrink type to force a horizontal row on a narrow screen",
+    routeHint: "Use arrows only when the source text has an order. Short stages can run left to right; long stages or a narrow screen should stack top to bottom",
+  },
+  steps: {
+    label: "Step diagram",
+    hint: "Use this to explain something step by step, with room for detail inside a step",
+    when: "A step-by-step explanation, with room for detail in a step",
+    whenNot: "This is not a time-scaled bar, not a checklist to follow, and not a stepper for watching state change",
+    routeHint: "Use a step diagram to make the order clear, and expand detail inside a step when needed. Do not turn it into a to-do list or a stepper unless the material really is that",
+  },
+  compare: {
+    label: "Comparison diagram",
+    hint: "Use this to compare two or three options under the same conditions",
+    when: "Two or three options compared under the same conditions",
+    whenNot: "If you are only listing traits and there is no shared condition, use an ordinary table or an aspect diagram",
+    routeHint: "Compare only when there is a real shared condition. Keep each side's facts, and do not invent a winner or a ranking",
+  },
+  timeline: {
+    label: "Timeline",
+    hint: "Use this to arrange events by date or time",
+    when: "Events arranged by date or time",
+    whenNot: "If the material is not a duration-scaled schedule, do not draw a Gantt chart with bar lengths",
+    routeHint: "Arrange events by the dates or times in the source, and keep that order. Do not turn it into a duration-scaled progress bar",
+  },
+  lanes: {
+    label: "Message sequence",
+    hint: "Use this to show who sent what to whom, and when",
+    when: "Who sent what to whom, and when",
+    whenNot: "This is not a general modeling language, and it does not support arbitrary branches, loops, or automatic routing",
+    routeHint: "Name the participants and the direction and order of their messages from the source. Do not add branches or loops that are not in the source",
+  },
+  tabs: {
+    label: "Tabs",
+    hint: "Use this when several groups of notes are independent and the reader should see one group at a time",
+    when: "Independent groups of notes, one group visible at a time",
+    whenNot: "Do not hide facts that must be compared at the same time. This is not app navigation",
+    routeHint: "Use tabs only when the groups can be read separately. Do not hide content that must be compared side by side",
+  },
+  chart: {
+    label: "Chart",
+    hint: "Use this to turn numbers you already have into bars, lines, or shares",
+    when: "Existing numbers drawn as bars, lines, or shares",
+    whenNot: "Do not invent data. If the result should change with an input, prefer a tunable chart",
+    routeHint: "Chart only real numbers from the material, and label the axes and units. Do not invent values",
+  },
+  tunable: {
+    label: "Tunable chart",
+    hint: "Use this when the reader should change one or two inputs and watch the result",
+    when: "One or two inputs the reader can change, and a result that follows",
+    whenNot: "If there is only one fixed example, or too many inputs, split it first. If one input should drive several outputs, use a conversion diagram",
+    routeHint: "Name the inputs and the conclusion that changes with them. The default state should already make sense. Do not ask the author to write a program",
+  },
+  converter: {
+    label: "Conversion diagram",
+    hint: "Use this when one input should produce several results at once",
+    when: "One input converted into several results at once",
+    whenNot: "If there is only one result, use a tunable chart. If each result needs its own control, split them first",
+    routeHint: "Keep the formulas and units for one input that yields several results. Do not invent conversions that are not in the material",
+  },
+  "code-walkthrough": {
+    label: "Code walkthrough",
+    hint: "Use this to walk through code line by line: what runs, and what the variables are",
+    when: "Line by line, what runs and what the variables are",
+    whenNot: "If you only need to show the code, use an ordinary code block. If the code is long, cut it to the key stretch first",
+    routeHint: "Walk a short, important stretch of code. Say which line is running and what the variables are at that moment. Do not change facts in the original code",
+  },
+  stepper: {
+    label: "Stepper",
+    hint: "Use this when the reader should pause on a step and see how state changes",
+    when: "The reader pauses on a step and sees how state changes",
+    whenNot: "If there are only two or three static stages, use a step diagram or a flow diagram",
+    routeHint: "Let the reader step through how state changes. If the stages are only static, use a step diagram instead",
+  },
+  trace: {
+    label: "Path callout",
+    hint: "Use this to mark how far you have walked on an existing flow or state diagram",
+    when: "A mark for how far you have walked on an existing flow or state diagram",
+    whenNot: "If you only need the structure, or there are too many nodes and edges, split it first",
+    routeHint: "Mark the current step on an existing state or flow diagram. Do not invent nodes or transitions that are not in the source",
+  },
+  plan: {
+    label: "Checklist",
+    hint: "Use this when the reader should follow items one by one and come back to check progress",
+    when: "A list the reader can follow and return to",
+    whenNot: "If these are only conceptual stages, use a list or a step diagram. If the reader should watch state change between steps, use a stepper",
+    routeHint: "List the steps in the order the reader will follow, and keep the wording from the source. Do not force conceptual stages into to-dos",
+  },
+  "inspect-grid": {
+    label: "Grid diagram",
+    hint: "Use this to mark which cells in a two-dimensional structure matter, and why",
+    when: "A two-dimensional structure, with certain cells called out",
+    whenNot: "If this is an ordinary data table and no cell needs a special note, use an ordinary table",
+    routeHint: "Present the two-dimensional structure as a grid, and point out the cells that need a special note and why. Do not force an ordinary table into a grid diagram",
+  },
+  other: {
+    label: "Other",
+    hint: "Use this when no built-in figure fits, and you need to combine text and graphics freely",
+    when: "No built-in figure fits, or you need to combine text and graphics freely",
+    whenNot: "Do not treat the built-in list as a closed allowlist, and do not learn a new syntax for this",
+  },
+};
+
+function authorPromptEn(item, en) {
+  if (item.open) {
+    return [
+      "Please combine text and graphics freely in one garden compose fence, from the material and the communication goal I provide. When no built-in figure fits, or several kinds of content need to sit together, use ordinary Markdown / HTML and the existing building blocks.",
+      "",
+      "My material:",
+      "- (paste the content, relationships, and source wording)",
+      "",
+      "My goal:",
+      "- (what the reader should understand, and what the focus is)",
+      "",
+      "Please:",
+      "- Organize only from the material; do not invent facts or conclusions",
+      "- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn a new syntax or write CSS",
+      "- The built-in figures in the list are a starting point, not a closed allowlist; if no recipe fits, extract the real relationships and combine building blocks",
+      "- Do not limit the result to one ready-made template; mix ordinary Markdown, safe HTML, and basic blocks such as cards, rows, columns, or steps when needed",
+    ].join("\n");
+  }
+  return [
+    `Please make a "${en.label}" diagram in garden compose from the material and the communication goal I provide.`,
+    "",
+    "My material:",
+    "- (paste the original items and wording to keep)",
+    "",
+    "My goal:",
+    "- (what the reader should see at a glance)",
+    "",
+    "Please:",
+    "- Organize only from the material; do not invent facts or conclusions",
+    "- Handle the graphic syntax, layout, and mobile reading yourself; do not ask me to learn tags or write CSS",
+    `- "${en.label}" is the recommended starting point: ${en.routeHint}`,
+    "- A recommended figure is not the only valid form; you may still combine necessary Markdown / HTML building blocks in the same compose fence",
+    "- Do not start a different author fence or a new syntax; use only garden compose",
+  ].join("\n");
+}
+
+export function handbookEnglish(item) {
+  const en = EN[item.name];
+  if (!en) throw new Error(`Missing English handbook copy for ${item.name}`);
+  return { ...en, prompt: authorPromptEn(item, en) };
+}
+
+export function previewSvgMarkup(item) {
+  const prefix = "data:image/svg+xml,";
+  if (!item.preview?.startsWith(prefix)) throw new Error(`Missing svg preview for ${item.name}`);
+  const svg = decodeURIComponent(item.preview.slice(prefix.length));
+  if (!svg.includes('width="72"') || !svg.includes('height="48"') || !svg.includes('viewBox="0 0 72 48"')) {
+    throw new Error(`Unexpected preview markup for ${item.name}`);
+  }
+  return svg.replace('width="72"', 'width="216"').replace('height="48"', 'height="144"');
+}
+
+export function generatedPaths() {
+  const files = [
+    ZH_INDEX,
+    EN_INDEX,
+  ];
+  for (const item of DIAGRAM_RECIPES) {
+    files.push(path.join(PREVIEW_DIR, `${item.name}.svg`));
+    files.push(path.join(ZH_DIR, `${item.name}.md`));
+    files.push(path.join(EN_DIR, `${item.name}.md`));
+  }
+  return files;
+}
+
+function yamlText(value) {
+  return JSON.stringify(String(value));
+}
+
+function zhPage(item, order) {
+  const fence = item.body.trim();
+  const aside = item.open
+    ? "「其他」不是又一种现成模板。现成图示无法表达、或需要把几种内容放在一起时，在同一个 `garden compose` 里用任意 Markdown、安全 HTML，以及卡片、行列、步骤等基础块自由组合。推荐说明草稿不是语法课，也不要把列表当成合法白名单。"
+    : "推荐说明草稿是起点，不是语法课，也不是唯一合法写法。需要时仍可在同一个 `garden compose` 里搭配 Markdown 或安全 HTML 基础块。";
+  return `---
+title: ${yamlText(item.label)}
+navTitle: ${yamlText(item.label)}
+description: ${yamlText(item.hint)}
+section: diagrams
+order: ${order}
+---
+
+${MARKER}
+![${item.label}示意](./previews/${item.name}.svg)
+
+${item.hint}。
+
+${item.whenNot}。
+
+Typora 和 VS Code / Cursor 共用同一份推荐列表。在 \`/garden\` 里，这一项的名称和适用说明与上面相同。选中后会插入下面的 \`garden compose\` 说明草稿。补全材料和表达目标，再交给 AI 编译。
+
+${aside}
+
+\`\`\`\`markdown
+${fence}
+\`\`\`\`
+`;
+}
+
+function enPage(item, order) {
+  const en = handbookEnglish(item);
+  const fence = "```garden compose\n" + en.prompt + "\n```";
+  const aside = item.open
+    ? "Other is not another ready-made template. When no built-in figure fits, or several kinds of content need to sit together, combine ordinary Markdown, safe HTML, and basic blocks such as cards, rows, columns, or steps in the same `garden compose` fence. The recommended brief is not a syntax lesson, and the list is not a closed allowlist."
+    : "The recommended brief is a starting point, not a syntax lesson, and not the only valid form. You may still combine Markdown or safe HTML building blocks in the same `garden compose` fence.";
+  return `---
+title: ${yamlText(en.label)}
+navTitle: ${yamlText(en.label)}
+description: ${yamlText(en.hint)}
+section: diagrams
+order: ${order}
+---
+
+${MARKER}
+![Schematic for ${en.label}](../../../components/diagrams/previews/${item.name}.svg)
+
+${en.hint}.
+
+${en.whenNot}.
+
+Typora and VS Code / Cursor share this list. In the \`/garden\` picker, this row is the same figure and the same use case. Choosing it inserts a \`garden compose\` brief. Fill in your material and goal, then ask the AI to compile the post.
+
+The built-in picker currently inserts that brief in Chinese. The English wording below is the same recommended brief, written for the English handbook so you can copy it when you write in English.
+
+${aside}
+
+\`\`\`\`markdown
+${fence}
+\`\`\`\`
+`;
+}
+
+function zhIndex() {
+  const count = DIAGRAM_RECIPES.length;
+  const named = DIAGRAM_RECIPES.filter((item) => !item.open).length;
+  const cards = DIAGRAM_RECIPES.map((item) => {
+    return `![${item.label}示意](./diagrams/previews/${item.name}.svg)
+
+**[${item.label}](/garden/components/diagrams/${item.name}/)** ${item.hint}。`;
+  }).join("\n\n");
+  return `---
+title: "推荐图示"
+navTitle: "推荐图示"
+description: "Typora 和 VS Code 内置推荐图示的名称、示意图、适用场景和推荐说明草稿。"
+section: diagrams
+order: 1
+---
+
+${MARKER}
+
+Typora 和 VS Code / Cursor 的 \`/garden\` 列表来自同一份内置推荐列表，目前共 ${count} 项：${named} 种常用图示，最后一项是「其他」。选中一项会插入统一的 \`garden compose\` 说明草稿，不是另一种作者围栏。推荐说明草稿用来写清材料和表达目标，不是语法课。
+
+「其他」用于现成图示无法表达、或需要自由组合图文的内容。不必把下面的列表当成合法白名单。
+
+入口和编译步骤见 [Compose](/garden/components/compose) 与 [语法检查与快捷输入](/garden/workflow)。
+
+${cards}
+`;
+}
+
+function enIndex() {
+  const count = DIAGRAM_RECIPES.length;
+  const named = DIAGRAM_RECIPES.filter((item) => !item.open).length;
+  const cards = DIAGRAM_RECIPES.map((item) => {
+    const en = handbookEnglish(item);
+    return `![Schematic for ${en.label}](../../components/diagrams/previews/${item.name}.svg)
+
+**[${en.label}](/garden/en/components/diagrams/${item.name}/)** ${en.hint}.`;
+  }).join("\n\n");
+  return `---
+title: "Recommended figures"
+navTitle: "Recommended figures"
+description: "Names, schematics, use cases, and recommended briefs for the built-in Typora and VS Code figure list."
+section: diagrams
+order: 1
+---
+
+${MARKER}
+
+The \`/garden\` list in Typora and in VS Code / Cursor comes from the same built-in list. There are currently ${count} items: ${named} common figures, and Other as the last item. Choosing one inserts a single \`garden compose\` brief, not a different author fence. That brief is for your material and goal, not a syntax lesson.
+
+Use Other when no built-in figure fits, or when you need to combine text and graphics freely. Do not treat the list below as a closed allowlist.
+
+For the entry and compile steps, see [Compose](/garden/en/components/compose) and [Checks & Shortcuts](/garden/en/workflow).
+
+${cards}
+`;
+}
+
+export function plannedFiles() {
+  const files = new Map();
+  files.set(path.join(PREVIEW_DIR, ".gitkeep"), "");
+  for (const item of DIAGRAM_RECIPES) {
+    files.set(path.join(PREVIEW_DIR, `${item.name}.svg`), `${previewSvgMarkup(item)}\n`);
+  }
+  files.set(ZH_INDEX, zhIndex());
+  files.set(EN_INDEX, enIndex());
+  DIAGRAM_RECIPES.forEach((item, index) => {
+    const order = (index + 1) * 10 + 1;
+    files.set(path.join(ZH_DIR, `${item.name}.md`), zhPage(item, order));
+    files.set(path.join(EN_DIR, `${item.name}.md`), enPage(item, order));
+  });
+  return files;
+}
+
+export function checkGenerated(root = ROOT) {
+  const issues = [];
+  const files = plannedFiles();
+  for (const [file, body] of files) {
+    if (file.endsWith(".gitkeep") && !body) continue;
+    const rel = path.relative(ROOT, file).split(path.sep).join("/");
+    const actualPath = path.join(root, rel);
+    if (!fs.existsSync(actualPath)) {
+      issues.push({ file: rel, message: "missing generated handbook file; run node scripts/handbook-diagrams.mjs" });
+      continue;
+    }
+    const actual = fs.readFileSync(actualPath, "utf8");
+    if (actual !== body) {
+      issues.push({ file: rel, message: "generated handbook file is stale; run node scripts/handbook-diagrams.mjs" });
+    }
+  }
+  for (const file of STALE_FILES) {
+    const rel = path.relative(ROOT, file).split(path.sep).join("/");
+    const actualPath = path.join(root, rel);
+    if (fs.existsSync(actualPath)) {
+      issues.push({ file: rel, message: "stale generated handbook file should be removed; run node scripts/handbook-diagrams.mjs" });
+    }
+  }
+  return issues;
+}
+
+export function writeGenerated() {
+  fs.mkdirSync(PREVIEW_DIR, { recursive: true });
+  fs.mkdirSync(ZH_DIR, { recursive: true });
+  fs.mkdirSync(EN_DIR, { recursive: true });
+  for (const [file, body] of plannedFiles()) {
+    if (file.endsWith(".gitkeep") && !body) continue;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, body);
+  }
+  for (const file of STALE_FILES) {
+    if (fs.existsSync(file)) fs.rmSync(file);
+  }
+}
+
+const isCli = path.basename(process.argv[1] ?? "") === "handbook-diagrams.mjs";
+if (isCli) {
+  const check = process.argv.includes("--check");
+  if (check) {
+    const issues = checkGenerated();
+    if (issues.length) {
+      for (const issue of issues) process.stderr.write(`${issue.file}: ${issue.message}\n`);
+      process.exitCode = 1;
+    }
+  } else {
+    writeGenerated();
+    process.stdout.write(`Wrote ${DIAGRAM_RECIPES.length} figure pages and previews from diagram-recipes.\n`);
+  }
+}

package/scripts/link-assets.mjs

@@ -300,6 +300,12 @@ export async function refreshDevLinkAssets({ siteRoot, files, ...options }) {
     } catch { selected = Object.keys(current); }
   }
   const changed = [...new Set(selected)].filter(file => Object.hasOwn(current, file)).map(file => path.join(siteRoot, file));
+  if (changed.length === 0 && previous) {
+    const cache = readLinkCache(siteRoot);
+    const cached = Object.keys(cache.favicons).length;
+    options.log?.(`链接图标：新取 0，沿用缓存 ${cached}，没有图标 0`);
+    return { cache, stats: { fetched: 0, cached, missing: 0 } };
+  }
   const result = await refreshLinkAssets({ siteRoot, ...options, files: changed });
   fs.mkdirSync(path.dirname(stateFile), { recursive: true });
   fs.writeFileSync(stateFile, JSON.stringify(current));

package/scripts/vinext-runtime.mjs

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function samePath(left, right) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+export function resolveRuntimeNodeModules(siteRoot, gardenPackageRoot) {
+  const packageModules = path.join(gardenPackageRoot, "node_modules");
+  const siteModules = path.join(siteRoot, "node_modules");
+  if (fs.existsSync(path.join(packageModules, "vinext"))) return packageModules;
+  if (fs.existsSync(path.join(siteModules, "vinext"))) return siteModules;
+  return packageModules;
+}
+
+export function ensureLink(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  try {
+    const stat = fs.lstatSync(to);
+    if (stat.isSymbolicLink() && fs.readlinkSync(to) === from) return;
+    if (stat.isSymbolicLink()) fs.unlinkSync(to);
+    else return;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  fs.symlinkSync(from, to);
+}
+
+/** Overlay Vinext's cwd so file: and npm installs share one layout. */
+export function ensureVinextRuntime({ siteRoot, gardenPackageRoot, lang = "zh" }) {
+  if (samePath(siteRoot, gardenPackageRoot)) return gardenPackageRoot;
+
+  const runtime = path.join(siteRoot, ".garden", "runtime");
+  fs.mkdirSync(runtime, { recursive: true });
+
+  const links = [
+    ["app", path.join(gardenPackageRoot, "app")],
+    ["ui", path.join(gardenPackageRoot, "ui")],
+    ["scripts", path.join(gardenPackageRoot, "scripts")],
+    ["docs", path.join(gardenPackageRoot, "docs")],
+    ["build", path.join(gardenPackageRoot, "build")],
+    ["worker", path.join(gardenPackageRoot, "worker")],
+    [".openai", path.join(gardenPackageRoot, ".openai")],
+    ["vite.config.ts", path.join(gardenPackageRoot, "vite.config.ts")],
+    ["next.config.ts", path.join(gardenPackageRoot, "next.config.ts")],
+    ["postcss.config.mjs", path.join(gardenPackageRoot, "postcss.config.mjs")],
+    ["tsconfig.json", path.join(gardenPackageRoot, "tsconfig.json")],
+    ["package.json", path.join(gardenPackageRoot, "package.json")],
+    ["node_modules", resolveRuntimeNodeModules(siteRoot, gardenPackageRoot)],
+    ["public", path.join(siteRoot, "public")],
+    ["content", path.join(siteRoot, "content")],
+    ["site.config.yaml", path.join(siteRoot, "site.config.yaml")],
+  ];
+
+  for (const name of [".env", ".env.local"]) {
+    const from = path.join(siteRoot, name);
+    if (fs.existsSync(from)) links.push([name, from]);
+  }
+
+  for (const [name, from] of links) {
+    if (fs.existsSync(from) || name === "public" || name === "content") {
+      if ((name === "public" || name === "content") && !fs.existsSync(from)) {
+        fs.mkdirSync(from, { recursive: true });
+      }
+      ensureLink(from, path.join(runtime, name));
+    }
+  }
+
+  // English sites: the runtime manifest is a copy with the English description, not a link.
+  // Remove the link first so the write never goes through it into the engine's own package.json.
+  if (lang === "en") {
+    const target = path.join(runtime, "package.json");
+    const manifest = JSON.parse(fs.readFileSync(path.join(gardenPackageRoot, "package.json"), "utf8"));
+    manifest.description = "A personal blog engine: write in Markdown, publish with GitHub Pages.";
+    fs.rmSync(target, { force: true });
+    fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+
+  return runtime;
+}

package/templates/site/Makefile

@@ -12,7 +12,7 @@ export GARDEN_EMBED_URL := $(value URL)
 export GARDEN_CHECK_FILE := $(value FILE)
 
 help:
-	@printf "%s\n" "Garden 常用命令：" "  make new                 用引擎创建文章草稿" '  make new TITLE="文章标题" SLUG=my-post DIR=writing' '  make embed URL="https://example.com"  拉取外部网页摘要' "  make skill               安装可交互图表 skill" "  make dev                 安装依赖并本地预览" "  make check               全量严格预检后 sync/build；FILE=路径 只限制预检" "  make check diff          只检查 Git 改动的 Markdown，不构建/跑全套测试" "  make build               构建公开站点" "  make update              检查、提交并触发自动发布"
+	@printf "%s\n" "Garden 常用命令：" "  make new                 用引擎创建文章草稿" '  make new TITLE="文章标题" SLUG=my-post DIR=writing' '  make embed URL="https://www.youtube.com/watch?v=..."  打印可粘贴的规范化视频链接或网页地址' "  make skill               安装可交互图表 skill" "  make dev                 安装依赖并本地预览" "  make check               全量严格预检后 sync/build；FILE=路径 只限制预检" "  make check diff          只检查 Git 改动的 Markdown，不构建/跑全套测试" "  make build               构建公开站点" "  make update              检查、提交并触发自动发布"
 
 new: prepare
 	npx garden new

package/templates/site/Makefile.en

@@ -12,7 +12,7 @@ export GARDEN_EMBED_URL := $(value URL)
 export GARDEN_CHECK_FILE := $(value FILE)
 
 help:
-	@printf "%s\n" "Common Garden commands:" "  make new                 Create a post draft with the engine" '  make new TITLE="Post title" SLUG=my-post DIR=writing' '  make embed URL="https://example.com"  Fetch external page metadata' "  make skill               Install interactive chart skills" "  make dev                 Install dependencies and preview locally" "  make check               Strict all-content preflight, then sync/build (FILE=path for one file preflight)" "  make check diff          Check only changed Markdown; no build or tests" "  make build               Build the public site" "  make update              Check, commit, and push to publish"
+	@printf "%s\n" "Common Garden commands:" "  make new                 Create a post draft with the engine" '  make new TITLE="Post title" SLUG=my-post DIR=writing' '  make embed URL="https://www.youtube.com/watch?v=..."  Print a paste-ready video or page URL' "  make skill               Install interactive chart skills" "  make dev                 Install dependencies and preview locally" "  make check               Strict all-content preflight, then sync/build (FILE=path for one file preflight)" "  make check diff          Check only changed Markdown; no build or tests" "  make build               Build the public site" "  make update              Check, commit, and push to publish"
 
 new: prepare
 	npx garden new

package/ui/compose/compose.css

@@ -865,16 +865,51 @@
 .g-compose-grid-item[data-span="4"] { grid-column: span 4; }
 
 .g-compose-icon {
+  --gc-icon-size: 15px;
   display: inline-block;
   flex: 0 0 auto;
-  width: 15px;
-  height: 15px;
+  width: var(--gc-icon-size);
+  height: var(--gc-icon-size);
   color: var(--ink);
   vertical-align: -2px;
 }
-.g-compose-icon[data-size="sm"] { width: 13px; height: 13px; }
-.g-compose-icon[data-size="lg"] { width: 18px; height: 18px; }
-.g-compose-icon[data-size="xl"] { width: 22px; height: 22px; }
+.g-compose-icon[data-size="sm"] { --gc-icon-size: 13px; }
+.g-compose-icon[data-size="lg"] { --gc-icon-size: 18px; }
+.g-compose-icon[data-size="xl"] { --gc-icon-size: 22px; }
+/* Align row-leading icons with the first line of adjacent text/headings rather than the top of half-leading. */
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-text:not([data-size="sm"]):not([data-size="lg"]):not([data-size="xl"])),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-text:first-child:not([data-size="sm"]):not([data-size="lg"]):not([data-size="xl"])),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-content:first-child) {
+  margin-top: max(0px, calc((1lh - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-text[data-size="sm"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-text[data-size="sm"]:first-child) {
+  margin-top: max(0px, calc((1.3125em - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-text[data-size="lg"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-text[data-size="lg"]:first-child) {
+  margin-top: max(0px, calc((1.125 * 1lh - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-text[data-size="xl"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-text[data-size="xl"]:first-child) {
+  margin-top: max(0px, calc((1.25 * 1lh - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:not([data-size="xl"]):has(+ .g-compose-h:not([data-size="sm"]):not([data-size="lg"]):not([data-size="xl"])),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:not([data-size="xl"]):has(+ .g-compose-group > .g-compose-h:first-child:not([data-size="sm"]):not([data-size="lg"]):not([data-size="xl"])) {
+  margin-top: max(0px, calc((1.4em - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-h[data-size="sm"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-h[data-size="sm"]:first-child) {
+  margin-top: max(0px, calc((1.1375em - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-h[data-size="lg"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-h[data-size="lg"]:first-child) {
+  margin-top: max(0px, calc((1.575em - var(--gc-icon-size)) / 2));
+}
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-h[data-size="xl"]),
+.g-compose-row:not([data-align="center"]):not([data-align="end"]) > .g-compose-icon:has(+ .g-compose-group > .g-compose-h[data-size="xl"]:first-child) {
+  margin-top: max(0px, calc((1.75em - var(--gc-icon-size)) / 2));
+}
 .g-compose-card[data-size="sm"] > .g-compose-icon {
   width: 14px;
   height: 14px;
@@ -1261,6 +1296,9 @@
     width: 100%;
     min-width: 0;
   }
+  .g-compose-row:not([data-wrap="nowrap"]) > .g-compose-icon {
+    margin-top: 0;
+  }
 
   /* Columnized centered rows stretch labels to 100% width, so align-items
      can center arrows but not text. Center direct labels only; explicit

package/ui/garden/markdown-links.mjs

@@ -3,6 +3,7 @@
  * and inline spans) is skipped, so a URL in a snippet is never a link.
  */
 import { INLINE_LINK_SOURCE } from "./markdown-destination.mjs";
+import { isPlayablePlayerUrl } from "./player.mjs";
 
 const FENCE = /^ {0,3}(`{3,}|~{3,})/u;
 
@@ -65,8 +66,10 @@ export const SOURCE_MARKER = "{source}";
 
 /**
  * A single-line paragraph whose only content is a web URL: bare, <autolink>,
- * or `[url](url)` (optional `{card}`). Those render as link cards and share
- * the OG fetch path with `{card}` markers.
+ * or `[url](url)` (optional `{card}`). Ordinary sites render as link cards and
+ * share the OG fetch path with `{card}` markers. A playable YouTube or
+ * Bilibili URL on its own line becomes a player instead, unless the author
+ * wrote `{card}`.
  */
 function standaloneUrl(line) {
   const trimmed = String(line ?? "").trim();
@@ -97,15 +100,15 @@ export function markdownLinks(markdown) {
     for (const match of text.matchAll(LINK)) {
       if (match[1] !== "!" && isWebUrl(linkUrl(match))) {
         const url = linkUrl(match);
-        links.push({ url, card: match[6] === CARD_MARKER || standalone.has(url) });
+        links.push({ url, card: match[6] === CARD_MARKER || (standalone.has(url) && !isPlayablePlayerUrl(url)) });
       }
     }
     const rest = text.replace(LINK, " ");
     for (const match of rest.matchAll(AUTOLINK)) {
-      links.push({ url: match[1], card: standalone.has(match[1]) });
+      links.push({ url: match[1], card: standalone.has(match[1]) && !isPlayablePlayerUrl(match[1]) });
     }
     for (const match of rest.replace(AUTOLINK, " ").matchAll(BARE)) {
-      links.push({ url: match[2], card: standalone.has(match[2]) });
+      links.push({ url: match[2], card: standalone.has(match[2]) && !isPlayablePlayerUrl(match[2]) });
     }
     return text;
   });