hd-garden 0.13.1 → 0.13.3

package/README.en.md

@@ -73,7 +73,7 @@ Ask your Agent to compile the post using the bundled `garden-ui` skill: it runs
 ```bash
 make new SLUG=writing-pace TITLE="Writing Pace" # Create a draft post in content/posts/
 make dev                                        # Sync content and start the local server
-CONTENT_INCLUDE_DRAFTS=1 make dev               # Preview drafts and future publishAt posts
+CONTENT_INCLUDE_DRAFTS=0 make dev              # Preview published posts only (optional)
 make check                                      # Run garden sync and garden build
 make update MESSAGE="Add writing-pace post"     # Check, commit, and push to origin
 npx garden check content/posts/writing-pace.md  # Validate front matter, components, and assets

package/README.md

@@ -75,7 +75,7 @@ Obsidian 插件这一轮不随包安装。
 ```bash
 make new SLUG=writing-pace TITLE="慢慢写"      # 在 content/posts/ 下创建文章草稿
 make dev                                       # 同步内容并启动本地预览
-CONTENT_INCLUDE_DRAFTS=1 make dev              # 连同草稿和未来定时文章一起预览
+CONTENT_INCLUDE_DRAFTS=0 make dev             # 只预览已发布文章（可选）
 make check                                     # 运行 garden sync 与 garden build 验证全站
 make update MESSAGE="新增一篇文章"             # 检查通过后提交并推送到远端仓库
 npx garden check content/posts/writing-pace.md # 单独检查一篇文章的标题、组件与资源路径

package/app/components/MarkdownArticle.tsx

@@ -5,12 +5,11 @@ import { remarkA2 } from "../lib/remark-a2.mjs";
 import { remarkLinkCard } from "../lib/remark-link-card.mjs";
 import {
   Children,
-  cloneElement,
   isValidElement,
   type HTMLAttributes,
   type ReactNode,
 } from "react";
-import { articleHeadingBase, autoNumbersHeadings, displayHeadingLevel, splitHeadingNumber } from "../lib/content";
+import { articleHeadingBase, displayHeadingLevel } from "../lib/content";
 import Link from "next/link";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
@@ -150,31 +149,7 @@ function CodeBlock({
   );
 }
 
-function stripPrefix(children: ReactNode, prefix: string): ReactNode {
-  let rest = prefix;
-  const walk = (node: ReactNode): ReactNode => {
-    if (!rest) return node;
-    if (typeof node === "string" || typeof node === "number") {
-      const value = String(node);
-      if (value.startsWith(rest)) {
-        const kept = value.slice(rest.length);
-        rest = "";
-        return kept;
-      }
-      if (rest.startsWith(value)) {
-        rest = rest.slice(value.length);
-        return "";
-      }
-      return value;
-    }
-    if (Array.isArray(node)) return node.map(walk);
-    if (isValidElement<{ children?: ReactNode }>(node)) {
-      return cloneElement(node, undefined, walk(node.props.children));
-    }
-    return node;
-  };
-  return walk(children);
-}
+
 
 
 /**
@@ -227,36 +202,18 @@ const headingText = (children: ReactNode) => {
   return parts.join("");
 };
 
-export function MarkdownArticle({ content, numbering, lang, fieldTables, refDemos, handbook }: { content: string; numbering?: boolean; lang?: UiLang; fieldTables?: boolean; refDemos?: boolean; handbook?: boolean }) {
+export function MarkdownArticle({ content, lang, fieldTables, refDemos, handbook }: { content: string; numbering?: boolean; lang?: UiLang; fieldTables?: boolean; refDemos?: boolean; handbook?: boolean }) {
   const internalRoute = handbook ? handbookRoute : siteRoute;
   const t = ui(lang);
   // Optional layer 2: a Worker that refreshes card text. Without it, cards stay as built.
   const cardWorker = content.includes("{card}") ? siteConfig.linkPreview?.worker : undefined;
-  const numbers = { h2: 0, h3: 0 };
-  const autoNumber = autoNumbersHeadings(content, numbering);
   const headingBase = articleHeadingBase(content);
-  const section = (depth: 2 | 3, children: ReactNode) => {
-    const raw = headingText(children).trim();
-    const split = splitHeadingNumber(raw);
-    if (split) {
-      if (depth === 2) { numbers.h2 += 1; numbers.h3 = 0; }
-      else numbers.h3 += 1;
-      const prefix = raw.slice(0, raw.length - split.text.length);
-      return { no: split.no, children: stripPrefix(children, prefix) };
-    }
-    if (!autoNumber) return { no: "", children };
-    if (depth === 2) { numbers.h2 += 1; numbers.h3 = 0; return { no: String(numbers.h2), children }; }
-    numbers.h3 += 1;
-    return { no: numbers.h2 ? `${numbers.h2}.${numbers.h3}` : String(numbers.h3), children };
-  };
   const heading = (source: 2 | 3 | 4, children: ReactNode, props: HTMLAttributes<HTMLHeadingElement> & { node?: unknown }) => {
     const level = displayHeadingLevel(source, headingBase);
     const Tag = level === 2 ? "h2" : level === 3 ? "h3" : "h4";
     const domProps = { ...props };
     Reflect.deleteProperty(domProps, "node");
-    if (level > 3) return <Tag {...domProps}>{children}</Tag>;
-    const sectioned = section(level as 2 | 3, children);
-    return <Tag {...domProps}>{sectioned.no ? <span className="sec-no">{sectioned.no}</span> : null}{sectioned.children}</Tag>;
+    return <Tag {...domProps}>{children}</Tag>;
   };
   const gardenComponents = {
     "garden-linkcard": (props: Record<string, string | undefined>) => (

package/app/components/TableOfContents.tsx

@@ -365,7 +365,6 @@ export function TableOfContents({
             onFocus={() => prefetchHeadingLayout(node.id)}
             aria-current={activeId === node.id ? "location" : undefined}
           >
-            {node.no ? <span className="t-no">{node.no}</span> : null}
             {node.text}
           </a>
           {node.children.length > 0 ? (

package/app/lib/content.ts

@@ -80,39 +80,22 @@ export { splitHeadingNumber };
  * Parses the same Markdown heading text that ReactMarkdown sends to
  * rehype-slug. Every heading depth advances the slugger so headings outside
  * the H2-H5 TOC range cannot shift the IDs shown in the directory.
- * `no` follows the prototype: keep an author-written number, otherwise
- * auto-number h2/h3 only when the article has no numbered headings and its
- * front matter does not say `numbering: false`.
+ * Heading text is literal: no synthetic numbers and no extraction of authored numbers.
  */
-export const extractHeadings = (markdown: string, { numbering }: { numbering?: boolean } = {}) => {
+export const extractHeadings = (markdown: string, _options: { numbering?: boolean } = {}) => {
+  // Accept the legacy option without changing authored heading text.
+  void _options;
   const slugger = new GithubSlugger();
-  const autoNumber = autoNumbersHeadings(markdown, numbering);
   const base = articleHeadingBase(markdown);
   const headings: Array<{ depth: number; text: string; id: string; no?: string }> = [];
   const tree = unified().use(remarkParse).use(markdownPlugins).parse(markdown);
-  let h2 = 0;
-  let h3 = 0;
 
   visit(tree, "heading", (node) => {
     const raw = toString(node).trim();
     const id = slugger.slug(raw);
     if (!(raw && node.depth >= 2 && node.depth <= 5)) return;
     const level = displayHeadingLevel(node.depth, base);
-    let text = raw;
-    let no: string | undefined;
-    if (level === 2 || level === 3) {
-      const split = splitHeadingNumber(raw);
-      if (split) {
-        no = split.no;
-        text = split.text;
-        if (level === 2) { h2 += 1; h3 = 0; }
-        else h3 += 1;
-      } else if (autoNumber) {
-        if (level === 2) { h2 += 1; h3 = 0; no = String(h2); }
-        else { h3 += 1; no = h2 ? `${h2}.${h3}` : String(h3); }
-      }
-    }
-    headings.push({ depth: level, text, id, ...(no ? { no } : {}) });
+    headings.push({ depth: level, text: raw, id });
   });
 
   return headings;

package/app/lib/heading-number.ts

@@ -13,10 +13,5 @@ const NUMBERED_ARTICLE = /^#{2,3}[ \t]+\d/m;
 /** True when the article writes its own section numbers (`## 2. …`). */
 export const articleUsesHeadingNumbers = (markdown: string) => NUMBERED_ARTICLE.test(markdown);
 
-/**
- * Whether h2/h3 get automatic numbers. Off when the author writes numbers, or
- * when the front matter says `numbering: false`. Author-written numbers are
- * always kept.
- */
-export const autoNumbersHeadings = (markdown: string, numbering?: boolean) =>
-  numbering !== false && !articleUsesHeadingNumbers(markdown);
+/** Compatibility export: headings are now always rendered literally. */
+export const autoNumbersHeadings = () => false;

package/bin/garden.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { startDev } from "../scripts/dev-server.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
@@ -312,12 +313,19 @@ function ensureDevGitHubLogin() {
   if (!/^GITHUB_SESSION_SECRET=\S+/m.test(text)) {
     text = upsertEnv(text, "GITHUB_SESSION_SECRET", randomBytes(32).toString("base64url"));
   }
-  fs.writeFileSync(local, text.endsWith("\n") ? text : `${text}\n`);
+  const next = text.endsWith("\n") ? text : `${text}\n`;
+  if (!fs.existsSync(local) || fs.readFileSync(local, "utf8") !== next) fs.writeFileSync(local, next);
 }
 
 async function runVinext(vinextArgs, { copyDist = false } = {}) {
-  await sync();
   const cwd = vinextRoot();
+  if (vinextArgs[0] === "dev") {
+    const { finished } = await startDev({ cwd, executable: resolveVinext(), args: vinextArgs.slice(1), env: siteEnv(), prepare: sync });
+    const result = await finished;
+    if (result.status !== 0) process.exit(result.status || 1);
+    return;
+  }
+  await sync();
   const result = spawnSync(process.execPath, [resolveVinext(), ...vinextArgs], {
     cwd,
     env: siteEnv(),
@@ -522,6 +530,10 @@ async function main() {
       await sync();
       break;
     case "dev":
+      // Preview drafts by default, without overriding an explicit opt-out.
+      // Scoped to this CLI process: sync, Vinext and its watcher inherit it;
+      // later build/check commands do not.
+      process.env.CONTENT_INCLUDE_DRAFTS ??= "1";
       ensureDevGitHubLogin();
       await runVinext(["dev", ...rest]);
       break;

package/docs/handbook/components/file/checklist.md

@@ -14,4 +14,4 @@
 | :--- | :--- |
 | `npx garden check content/posts/<slug>.md` | 检查单篇文章的组件字段、代码对比与图片附件路径 |
 | `make check` | 运行 `npx garden sync && npx garden build` 校验全站构建 |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | 在本地连同草稿和定时文章一起预览 |
+| `make dev` | 在本地连同草稿和定时文章一起预览 |

package/docs/handbook/en/components/file/checklist.md

@@ -14,4 +14,4 @@ Before running `make update` to push changes, verify the following items:
 | :--- | :--- |
 | `npx garden check content/posts/<slug>.md` | Checks a single post's component fields, code diffs, and local asset paths |
 | `make check` | Runs `npx garden sync && npx garden build` to validate the full site build |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | Previews drafts and scheduled posts locally |
+| `make dev` | Previews drafts and scheduled posts locally |

package/docs/handbook/en/reference/file/checklist.md

@@ -14,4 +14,4 @@ Before running `make update` to push changes, verify the following items:
 | :--- | :--- |
 | `npx garden check content/posts/<slug>.md` | Checks a single post's component fields, code diffs, and local asset paths |
 | `make check` | Runs `npx garden sync && npx garden build` to validate the full site build |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | Previews drafts and scheduled posts locally |
+| `make dev` | Previews drafts and scheduled posts locally |

package/docs/handbook/en/start.md

@@ -59,10 +59,10 @@ make new DIR=network SLUG=tcp-bbr TITLE="TCP BBR Notes"
 > [!NOTE] Note
 > `SLUG` may only contain lowercase letters, digits, and hyphens (`a-z`, `0-9`, `-`), never `/`; pass subdirectories via `DIR`. `make new` reads only `SLUG`, `TITLE`, and `DIR`.
 
-Newly created files default to `draft: true`. Set `CONTENT_INCLUDE_DRAFTS=1` to preview drafts or future-dated (`publishAt`) posts locally:
+Newly created files default to `draft: true`. `make dev` previews drafts and future-dated (`publishAt`) posts by default. Use `CONTENT_INCLUDE_DRAFTS=0 make dev` to opt out. Production builds still exclude them by default:
 
 ```bash
-CONTENT_INCLUDE_DRAFTS=1 make dev
+make dev
 ```
 
 ### Creating a Thought
@@ -76,7 +76,7 @@ The site `Makefile` and `garden` CLI provide these commands:
 | Command | What It Runs |
 | :--- | :--- |
 | `make dev` | Runs `make prepare` to check dependencies, then runs `npx garden dev` (which syncs content and starts the dev server) |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | Previews `draft: true` drafts and future `publishAt` posts alongside published content |
+| `CONTENT_INCLUDE_DRAFTS=0 make dev` | Optional: preview published posts only, excluding drafts and future posts |
 | `make new SLUG=xxx TITLE="Title" DIR=subdir` | Calls `npx garden new` to create a draft post under `content/posts/` (`DIR` is optional) |
 | `make check` | Runs `npx garden sync && npx garden build` in the site repo to verify content sync and the production build |
 | `npx garden check content/posts/xxx.md` | Checks a single Markdown post's title, component fields, code diffs, and local asset paths |

package/docs/handbook/reference/file/checklist.md

@@ -14,4 +14,4 @@
 | :--- | :--- |
 | `npx garden check content/posts/<slug>.md` | 检查单篇文章的组件字段、代码对比与图片附件路径 |
 | `make check` | 运行 `npx garden sync && npx garden build` 校验全站构建 |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | 在本地连同草稿和定时文章一起预览 |
+| `make dev` | 在本地连同草稿和定时文章一起预览 |

package/docs/handbook/start.md

@@ -59,10 +59,10 @@ make new DIR=network SLUG=tcp-bbr TITLE="TCP BBR 拥塞控制笔记"
 > [!NOTE]
 > `SLUG` 只能包含小写字母、数字和连字符（`a-z`、`0-9`、`-`），不能包含 `/`；子目录必须用 `DIR` 参数传入。`make new` 只读取 `SLUG`、`TITLE` 和 `DIR` 三个变量。
 
-新建的文件默认带有 `draft: true`。本地预览草稿或未来定时文章（`publishAt`）时，加上环境变量 `CONTENT_INCLUDE_DRAFTS=1`：
+新建的文件默认带有 `draft: true`。`make dev` 默认预览草稿和未来定时文章（`publishAt`）；用 `CONTENT_INCLUDE_DRAFTS=0 make dev` 可关闭。正式构建仍默认排除它们：
 
 ```bash
-CONTENT_INCLUDE_DRAFTS=1 make dev
+make dev
 ```
 
 ### 新建随想
@@ -76,7 +76,7 @@ CONTENT_INCLUDE_DRAFTS=1 make dev
 | 命令 | 实际执行的操作 |
 | :--- | :--- |
 | `make dev` | 先执行 `make prepare` 检查依赖，再运行 `npx garden dev`（内部自动执行同步并启动开发服务器） |
-| `CONTENT_INCLUDE_DRAFTS=1 make dev` | 连同 `draft: true` 草稿和未到 `publishAt` 时间的文章一起预览 |
+| `CONTENT_INCLUDE_DRAFTS=0 make dev` | 可选：只预览已发布文章，排除草稿和未来定时文章 |
 | `make new SLUG=xxx TITLE="标题" DIR=子目录` | 调用 `npx garden new` 在 `content/posts/` 下生成新文章草稿（`DIR` 可省略） |
 | `make check` | 在站点仓库中运行 `npx garden sync && npx garden build`，验证全站同步与生产构建 |
 | `npx garden check content/posts/xxx.md` | 单独检查某篇 Markdown 文章的标题、组件字段、代码对比与本地附件路径 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "private": false,
   "description": "\u7528 Markdown \u5199\u4f5c\u3001\u7528 GitHub Pages \u53d1\u5e03\u7684\u4e2a\u4eba\u535a\u5ba2\u5f15\u64ce\u3002",
   "license": "MIT",

package/scripts/build-content.mjs

@@ -1,5 +1,13 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
+
+// Preserve mtimes of unchanged generated output to avoid dev reload storms.
+function writeChanged(file, value) {
+  const next = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  if (fs.existsSync(file) && fs.readFileSync(file).equals(next)) return;
+  fs.writeFileSync(file, next);
+}
+
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
@@ -201,7 +209,7 @@ function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
       .join(path.sep)}${extension.toLowerCase()}`;
     const destination = path.join(generatedMediaRoot, safeRelative);
     fs.mkdirSync(path.dirname(destination), { recursive: true });
-    fs.copyFileSync(absoluteSource, destination);
+    writeChanged(destination, fs.readFileSync(absoluteSource));
     const url = `${basePath}/media/${safeRelative.split(path.sep).map(encodeURIComponent).join("/")}`;
     assetCache.set(absoluteSource, url);
     assetFiles.set(url, { source: absoluteSource, destination });
@@ -363,7 +371,7 @@ function resolveFileEntry(file, markdownPath, sourcePath, options = {}) {
     const { content } = matter(fs.readFileSync(resolved.path, "utf8"));
     const html = renderFilePreview(rewriteMarkdownAssets(content.trim(), resolved.path, sourcePath, assetOptions), { lang });
     const { destination } = assetFiles.get(url.split(/[?#]/u, 1)[0]);
-    fs.writeFileSync(previewFileName(destination), previewDocument(html, { title: entry.title, lang, icon: previewIcon() }));
+    writeChanged(previewFileName(destination), previewDocument(html, { title: entry.title, lang, icon: previewIcon() }));
     next.previewSrc = previewFileName(url.split(/[?#]/u, 1)[0]);
   }
   return next;
@@ -748,7 +756,10 @@ function readHandbookDocs() {
   return walk(handbookRoot).sort((a, b) => a.order - b.order || a.path.localeCompare(b.path));
 }
 
-fs.rmSync(generatedMediaRoot, { recursive: true, force: true });
+// Keep existing preview assets while regenerating; deleting the whole tree
+// triggers browser reloads before validation finishes (and destroys last-good
+// output on an invalid save). Public builds still clean stale assets.
+if (uiMode !== "preview") fs.rmSync(generatedMediaRoot, { recursive: true, force: true });
 
 const posts = readMarkdownTree(path.join(contentRoot, "posts"), "post").sort(
   (a, b) => Date.parse(b.date) - Date.parse(a.date),
@@ -924,9 +935,9 @@ export const imageSizes: Record<string, { width: number; height: number }> = ${J
 `;
 
 fs.mkdirSync(path.dirname(output), { recursive: true });
-fs.writeFileSync(output, source);
+writeChanged(output, source);
 const fullIndex = buildFullIndex({ posts, columns, thoughts });
-fs.writeFileSync(
+writeChanged(
   siteConfigOutput,
   `// Generated by garden sync. Edit site.config.yaml instead.
 export const siteConfig = ${JSON.stringify(siteConfig, null, 2)} as const;
@@ -942,11 +953,11 @@ export const siteLinks = ${JSON.stringify({ address: siteAddress, basePath, trai
 `,
 );
 fs.mkdirSync(path.join(root, "public"), { recursive: true });
-fs.writeFileSync(path.join(root, "public", "search-index.json"), JSON.stringify(buildSearchIndex({ posts, columns, thoughts }, { lang: siteLang })));
+writeChanged(path.join(root, "public", "search-index.json"), JSON.stringify(buildSearchIndex({ posts, columns, thoughts }, { lang: siteLang })));
 for (const name of fs.readdirSync(path.join(root, "public"))) {
   if (/^search-full\.[0-9a-f]+\.json$/u.test(name) && name !== fullIndex.fileName) fs.rmSync(path.join(root, "public", name));
 }
-fs.writeFileSync(path.join(root, "public", fullIndex.fileName), fullIndex.json);
+writeChanged(path.join(root, "public", fullIndex.fileName), fullIndex.json);
 
 const escapeXml = (value) =>
   value
@@ -988,7 +999,7 @@ function writeRssFeed(fileName, entries) {
       <content:encoded><![CDATA[${cdata(marked.parse(contentForFeed(entry.content, { pageUrl: `${publicBaseUrl}${entry.path}`, siteUrl: publicBaseUrl })))}]]></content:encoded>
     </item>`).join("");
 
-  fs.writeFileSync(path.join(publicRoot, fileName), `<?xml version="1.0" encoding="UTF-8" ?>
+  writeChanged(path.join(publicRoot, fileName), `<?xml version="1.0" encoding="UTF-8" ?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
   <channel>
     <title>${escapeXml(siteName)}</title>
@@ -1019,16 +1030,16 @@ const sitemapEntries = [
   ].map(pageAddress)),
 ];
 // Card URLs in published entries: the only pages the link-card Worker may read.
-fs.writeFileSync(
+writeChanged(
   path.join(publicRoot, "link-allowlist.json"),
   `${JSON.stringify({ urls: [...new Set([...posts, ...columns, ...thoughts].flatMap((entry) => cardUrls(entry.content)))].sort() }, null, 2)}\n`,
 );
-fs.writeFileSync(path.join(publicRoot, "sitemap.xml"), `<?xml version="1.0" encoding="UTF-8" ?>
+writeChanged(path.join(publicRoot, "sitemap.xml"), `<?xml version="1.0" encoding="UTF-8" ?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${sitemapEntries.map((entry) => `
   <url><loc>${escapeXml(`${publicBaseUrl}${entry}`)}</loc></url>`).join("")}
 </urlset>
 `);
-fs.writeFileSync(path.join(publicRoot, "robots.txt"), `User-agent: *\nAllow: /\nSitemap: ${publicBaseUrl}/sitemap.xml\n`);
+writeChanged(path.join(publicRoot, "robots.txt"), `User-agent: *\nAllow: /\nSitemap: ${publicBaseUrl}/sitemap.xml\n`);
 console.log(
   `Synced ${posts.length} posts, ${columns.length} column entries, and ${thoughts.length} thoughts (${contentHash}).`,
 );

package/scripts/dev-server.mjs

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+import net from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+
+const alive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== "ESRCH"; }
+};
+const read = (file) => {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+};
+const ps = (pid, field) => execFileSync("ps", ["-p", String(pid), "-o", `${field}=`], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } }).trim();
+function identity(pid, executable) {
+  if (process.platform !== "linux" && process.platform !== "darwin") throw new Error("Automatic dev replacement requires Linux or macOS process inspection.");
+  if (Number(ps(pid, "uid")) !== process.getuid()) throw new Error("Dev process belongs to another user; nothing was stopped.");
+  const start = Date.parse(ps(pid, "lstart"));
+  let cwd;
+  let matches;
+  if (process.platform === "linux") {
+    cwd = fs.realpathSync(`/proc/${pid}/cwd`);
+    const args = fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
+    matches = args[1] === executable && args[2] === "dev";
+  } else {
+    const entries = execFileSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], { encoding: "utf8" });
+    cwd = fs.realpathSync(entries.split("\n").find((line) => line.startsWith("n"))?.slice(1) ?? "");
+    const command = ps(pid, "command");
+    // Exact script path and subcommand, not a substring such as `node -e ...`.
+    const node = ps(pid, "comm");
+    matches = command.startsWith(`${node} ${executable} dev`) && /^(?:\s|$)/u.test(command.slice(`${node} ${executable} dev`.length));
+  }
+  if (!matches || !Number.isFinite(start)) throw new Error(`PID ${pid} is not the expected Vinext dev process.`);
+  return { cwd, start };
+}
+async function portFree(lock) {
+  if (!Number.isInteger(lock.port) || lock.port < 1 || lock.port > 65535) return true;
+  // Only probe loopback; never connect to a target supplied by lock metadata.
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port: lock.port });
+    socket.setTimeout(200);
+    socket.once("connect", () => { socket.destroy(); resolve(false); });
+    socket.once("error", () => { socket.destroy(); resolve(true); });
+    socket.once("timeout", () => { socket.destroy(); resolve(false); });
+  });
+}
+
+/** Serialize same-runtime replacement/startup. Never infer ownership from a port. */
+export async function startDev({ cwd, executable, args = [], env = process.env, prepare = async () => {}, timeoutMs = 15000, stdio = "inherit" }) {
+  cwd = fs.realpathSync(cwd);
+  executable = fs.realpathSync(executable);
+  const guard = path.join(cwd, ".garden-dev-start");
+  const lockPath = path.join(cwd, ".vinext/dev/lock.json");
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    try {
+      fs.mkdirSync(guard);
+      fs.writeFileSync(path.join(guard, "owner.json"), JSON.stringify({ pid: process.pid }));
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const owner = read(path.join(guard, "owner.json"));
+      if (owner && !alive(owner.pid)) throw new Error(`Interrupted Garden startup guard at ${guard}; no process was stopped. Remove this guard only after confirming no startup is in progress.`);
+      if (Date.now() >= deadline) throw new Error("Another Garden dev start is in progress; ownership could not be safely resolved.");
+      await delay(100);
+    }
+  }
+  let child;
+  try {
+    const lock = read(lockPath);
+    if (lock && alive(lock.pid)) {
+      if (lock.pid === process.pid) throw new Error("Refusing to replace this process.");
+      const previous = identity(lock.pid, executable);
+      if (previous.cwd !== cwd || fs.realpathSync(lock.cwd) !== cwd || !Number.isFinite(lock.startedAt) || previous.start > lock.startedAt + 1000 || lock.startedAt - previous.start > 120000) {
+        throw new Error("Dev lock ownership is unproven (runtime or process start time mismatch); nothing was stopped.");
+      }
+      // Recheck identity immediately before signalling to reduce PID-reuse races.
+      const current = identity(lock.pid, executable);
+      if (current.start !== previous.start || current.cwd !== cwd || read(lockPath)?.startedAt !== lock.startedAt) throw new Error("Dev owner changed during replacement; nothing was stopped.");
+      process.kill(lock.pid, "SIGTERM");
+      while (alive(lock.pid) || !(await portFree(lock))) {
+        if (Date.now() >= deadline) throw new Error("Previous dev server did not release its process/port in time; no force-kill attempted.");
+        await delay(100);
+      }
+      const remaining = read(lockPath);
+      if (remaining && remaining.pid !== lock.pid) throw new Error("Dev lock changed during shutdown; refusing to replace another owner.");
+    }
+    // Vinext itself takes over dead-PID locks. Do not unlink someone else's lock.
+    await prepare();
+    child = spawn(process.execPath, [executable, "dev", ...args], { cwd, env, stdio });
+    const exited = new Promise((resolve, reject) => { child.once("error", reject); child.once("exit", (code, signal) => resolve({ status: code, signal })); });
+    const forward = (signal) => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); };
+    const interrupt = () => forward("SIGINT");
+    const terminate = () => forward("SIGTERM");
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    const finished = exited.finally(() => { process.off("SIGINT", interrupt); process.off("SIGTERM", terminate); });
+    // The guard only covers startup, not the server's whole lifetime.
+    const startupDeadline = Date.now() + timeoutMs;
+    while (child.exitCode === null && child.signalCode === null) {
+      if (read(lockPath)?.pid === child.pid) break;
+      if (Date.now() >= startupDeadline) {
+        child.kill("SIGTERM");
+        await Promise.race([finished, delay(1000)]);
+        throw new Error("Dev server did not establish its runtime lock in time; graceful stop requested (no force kill).");
+      }
+      await delay(100);
+    }
+    return { child, finished };
+  } finally {
+    fs.rmSync(guard, { recursive: true });
+  }
+}

package/scripts/new-post.mjs

@@ -67,12 +67,12 @@ async function main() {
   if (lang === "en") {
     console.log(`Created draft: ${path.relative(root, destination)}`);
     console.log(`Post URL: /blog/${[...segments, slug].join("/")}/`);
-    console.log("Preview: CONTENT_INCLUDE_DRAFTS=1 make dev");
+    console.log("Preview: make dev");
     console.log("Before publishing, fill in description, tags, and body, set draft to false, then run make update.");
   } else {
     console.log(`已创建草稿：${path.relative(root, destination)}`);
     console.log(`文章路径：/blog/${[...segments, slug].join("/")}/`);
-    console.log("预览：CONTENT_INCLUDE_DRAFTS=1 make dev");
+    console.log("预览：make dev");
     console.log("发布前请完善摘要、标签与正文，并将 draft 改为 false，再运行 make update。");
   }
 }

package/templates/site/README.en.md

@@ -8,6 +8,8 @@ make new TITLE="Hello, World" SLUG=hello
 make dev
 ```
 
+`make dev`, `npm run dev`, and `npx garden dev` preview drafts and future scheduled posts by default. Opt out with `CONTENT_INCLUDE_DRAFTS=0 make dev`. Production builds exclude them by default.
+
 Running `npx garden dev` for the first time fills in any missing `Makefile` or skills and creates `.env.local`. Cursor and Codex read `.agents/skills/` automatically when opening this repository. Run `npx garden skill` anytime to update the bundled skills.
 
 `npx hd-garden init` copies the VS Code / Cursor and Typora Intelligent UI plugins into `.garden/editors/` and asks whether to install them when the terminal is interactive. Run `npx garden editors install` later (`--yes` installs both, `--vscode` or `--typora` installs one). Typora needs typora-community-plugin first; then enable the plugin under Settings, Installed plugins. Use the plugins to insert a plain `garden` brief for the `garden-ui` skill to compile, preview a component, and open the catalog. In Typora, type `/` and choose `/garden` to list each component with a small preview image. Hand `Compile this post:` to the skill when you want it compiled.
@@ -15,3 +17,5 @@ Running `npx garden dev` for the first time fills in any missing `Makefile` or s
 Comments are disabled by default. Before publishing, open [Giscus](https://giscus.app), write the repository, repository ID, category, and category ID into `.env.local`, and set the matching `GISCUS_REPO`, `GISCUS_REPO_ID`, `GISCUS_CATEGORY`, and `GISCUS_CATEGORY_ID` under GitHub Actions Variables. Leaving them empty fails the publish workflow. To publish without comments, set `GISCUS_DISABLED` to `1`.
 
 To upgrade the engine, update `hd-garden` in `package.json` to the new version and run `npm install`.
+
+Running `make dev` again gracefully replaces a verified Vinext process from the same project, never an unrelated port owner. Markdown edits, additions and deletions update the preview. Headings stay literal; ranges like `4~6` are plain text and strikethrough requires `~~text~~`.

package/templates/site/README.md

@@ -8,6 +8,8 @@ make new TITLE="你好，世界" SLUG=hello
 make dev
 ```
 
+`make dev`、`npm run dev` 和 `npx garden dev` 默认预览草稿及未来定时文章。可用 `CONTENT_INCLUDE_DRAFTS=0 make dev` 关闭；正式构建默认排除这些内容。
+
 第一次 `npx garden dev` 会补齐 Makefile 和 skill，并创建 `.env.local`。Cursor / Codex 打开这个仓库后会读到 `.agents/skills/`。要更新 skill，再运行 `npx garden skill`。
 
 `npx hd-garden init` 会把 VS Code / Cursor 与 Typora 的 Intelligent UI 插件放到 `.garden/editors/`，并在交互终端里询问要不要安装。之后可以运行 `npx garden editors install`（加 `--yes` 则直接安装，`--vscode` / `--typora` 只装一个）。Typora 需要先装 typora-community-plugin，再在「设置 → 已安装插件」里勾选。插件用来插入想法（一段给 `garden-ui` skill 编译的 `garden` 围栏，不是写好的 YAML）、预览组件、打开清单，并把「编译这篇」交给 skill。Typora 里输入 `/` 选 `/garden`，再从带小预览图的列表里选。
@@ -15,3 +17,5 @@ make dev
 评论默认关闭。发布前打开 [Giscus](https://giscus.app/zh-CN)，把仓库、仓库 ID、分类、分类 ID 写入 `.env.local`，并在 GitHub Actions Variables 设置同名的 `GISCUS_REPO`、`GISCUS_REPO_ID`、`GISCUS_CATEGORY`、`GISCUS_CATEGORY_ID`。留空会让发布失败。确定不开放评论时，把 `GISCUS_DISABLED` 设为 `1`。
 
 升级引擎：把 `package.json` 里的 `hd-garden` 改到新版本，例如 `^0.4.0`，再运行 `npm install`。
+
+再次运行 `make dev` 会先温和停止经验证属于同一项目的旧 Vinext，再启动新服务；不会按端口号杀死无关进程。修改、新建或删除 Markdown 会自动更新预览。标题按原文显示；范围 `4~6` 不作删除线，显式删除线用 `~~删除线~~`。

package/ui/garden/markdown-syntax.mjs

@@ -9,4 +9,4 @@ import remarkMath from "remark-math";
  * (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];
+export const markdownSyntaxPlugins = [[remarkGfm, { singleTilde: false }], remarkCjkFriendly, remarkBreaks, remarkMath];

package/vite.config.ts

@@ -46,7 +46,7 @@ const localBindingConfig = {
 
 function gardenContent() {
   const sync = (mode?: "preview") => {
-    spawnSync(process.execPath, [path.join(gardenPackageRoot, "scripts", "build-content.mjs")], {
+    return spawnSync(process.execPath, [path.join(gardenPackageRoot, "scripts", "build-content.mjs")], {
       cwd: siteRoot,
       env: { ...process.env, GARDEN_SITE: siteRoot, ...(mode ? { GARDEN_CONTENT_MODE: mode } : {}) },
       stdio: "inherit",
@@ -78,12 +78,37 @@ function gardenContent() {
       const contentDir = path.join(siteRoot, "content");
       const configFile = path.join(siteRoot, "site.config.yaml");
       server.watcher.add([contentDir, configFile]);
-      server.watcher.on("change", (file) => {
-        if (file.startsWith(contentDir) || file === configFile) {
-          // While editing, a broken ui block shows as an error card instead of stopping the server.
-          sync("preview");
-          server.ws.send({ type: "full-reload" });
-        }
+      let pending: ReturnType<typeof setTimeout> | undefined;
+      const onContentEvent = (file: string) => {
+        const relative = path.relative(contentDir, file);
+        if (file !== configFile && (relative.startsWith("..") || path.isAbsolute(relative))) return;
+        clearTimeout(pending);
+        // Coalesce editor atomic writes/renames; regenerate before asking browsers
+        // to reload, including newly created and deleted Markdown routes.
+        pending = setTimeout(() => {
+          const result = sync("preview");
+          if (result.status === 0) {
+            // The generator is synchronous; filesystem notifications have not
+            // necessarily reached Vite yet. Invalidate generated imports before
+            // any browser can request the new document.
+            for (const environment of Object.values(server.environments)) {
+              for (const generated of [generatedContent, generatedSiteConfig]) {
+                const modules = environment.moduleGraph.getModulesByFile(generated);
+                for (const generatedModule of modules ?? []) environment.moduleGraph.invalidateModule(generatedModule);
+              }
+            }
+            server.ws.send({ type: "full-reload" });
+          }
+        }, 100);
+      };
+      server.watcher.on("add", onContentEvent);
+      server.watcher.on("change", onContentEvent);
+      server.watcher.on("unlink", onContentEvent);
+      server.httpServer?.once("close", () => {
+        clearTimeout(pending);
+        server.watcher.off("add", onContentEvent);
+        server.watcher.off("change", onContentEvent);
+        server.watcher.off("unlink", onContentEvent);
       });
     },
   };