hd-garden 0.3.13 → 0.4.1

package/app/components/garden/chrome.tsx

@@ -0,0 +1,350 @@
+"use client";
+
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { acceptSandboxSizeMessage } from "./sandbox-message";
+
+const COPY_ICON = (
+  <svg viewBox="0 0 16 16" aria-hidden="true">
+    <rect x="5.25" y="5.25" width="8.5" height="8.5" rx="1.5" />
+    <path d="M10.75 5.25V3.75a1.5 1.5 0 0 0-1.5-1.5h-5.5a1.5 1.5 0 0 0-1.5 1.5v5.5a1.5 1.5 0 0 0 1.5 1.5h1.5" />
+  </svg>
+);
+const ENTER_ICON = (
+  <svg viewBox="0 0 16 16" aria-hidden="true">
+    <path d="M2.5 6V2.5H6M10 2.5h3.5V6M13.5 10v3.5H10M6 13.5H2.5V10" />
+  </svg>
+);
+const EXIT_ICON = (
+  <svg viewBox="0 0 16 16" aria-hidden="true">
+    <path d="M6 2.5V6H2.5M13.5 6H10V2.5M10 13.5V10h3.5M2.5 10H6v3.5" />
+  </svg>
+);
+
+function writeClipboard(text: string) {
+  if (navigator.clipboard && window.isSecureContext) return navigator.clipboard.writeText(text);
+  return new Promise<void>((resolve, reject) => {
+    const area = document.createElement("textarea");
+    area.value = text;
+    area.setAttribute("readonly", "");
+    area.style.position = "fixed";
+    area.style.opacity = "0";
+    document.body.appendChild(area);
+    area.select();
+    try {
+      if (document.execCommand("copy")) resolve();
+      else reject(new Error("copy"));
+    } catch (error) {
+      reject(error);
+    } finally {
+      area.remove();
+    }
+  });
+}
+
+export function CopyButton({ getText, label = "复制代码" }: { getText: () => string; label?: string }) {
+  const [done, setDone] = useState(false);
+  const timer = useRef<number>(0);
+
+  return (
+    <>
+      <button
+        type="button"
+        className={`ux-btn ux-copy${done ? " ux-done" : ""}`}
+        aria-label={done ? "已复制" : label}
+        title={done ? "已复制" : label}
+        onClick={() => {
+          const text = getText();
+          writeClipboard(text).then(() => {
+            setDone(true);
+            window.clearTimeout(timer.current);
+            timer.current = window.setTimeout(() => setDone(false), 1500);
+          }).catch(() => setDone(false));
+        }}
+      >
+        {done ? "已复制" : COPY_ICON}
+      </button>
+      <span className="ux-live" aria-live="polite">{done ? "已复制到剪贴板" : ""}</span>
+    </>
+  );
+}
+
+export function CodeCopy({ children }: { children: ReactNode }) {
+  const ref = useRef<HTMLDivElement>(null);
+  return (
+    <div className="ux-cb" ref={ref}>
+      {children}
+      <CopyButton getText={() => {
+        const pre = ref.current?.querySelector("pre");
+        const code = pre?.querySelector("code") ?? pre;
+        return (code?.textContent ?? "").replace(/\n$/u, "");
+      }} />
+    </div>
+  );
+}
+
+function diffLines(source: string) {
+  return source.replace(/\n$/u, "").split("\n").map((line) => {
+    const kind = line.startsWith("+") ? "add" : line.startsWith("-") ? "del" : "ctx";
+    const body = kind === "ctx" ? line.replace(/^ /u, "") : line.slice(1);
+    const mark = kind === "add" ? "+" : kind === "del" ? "−" : " ";
+    const spoken = kind === "add" ? "（新增）" : kind === "del" ? "（删除）" : "";
+    return { kind, body, mark, spoken };
+  });
+}
+
+export function CodeDiff({
+  code,
+  diff,
+  next,
+}: {
+  code: ReactNode;
+  diff: string;
+  next: string;
+}) {
+  const [tab, setTab] = useState(0);
+  const base = useId();
+  const tabs = ["代码", "对比上一版"];
+
+  return (
+    <div className="g-tabs g-code-group g-codediff" data-g="tabs">
+      <div role="tablist" aria-label="代码">
+        {tabs.map((label, index) => (
+          <button
+            key={label}
+            type="button"
+            role="tab"
+            id={`${base}-t${index}`}
+            aria-controls={`${base}-p${index}`}
+            aria-selected={tab === index}
+            tabIndex={tab === index ? 0 : -1}
+            onClick={() => setTab(index)}
+            onKeyDown={(event) => {
+              const nextIndex = event.key === "ArrowRight" || event.key === "ArrowLeft" ? (index + 1) % 2 : -1;
+              if (nextIndex < 0) return;
+              event.preventDefault();
+              setTab(nextIndex);
+            }}
+          >
+            {label}
+          </button>
+        ))}
+        <CopyButton getText={() => {
+          if (tab === 1) return next;
+          const root = document.getElementById(`${base}-p0`);
+          return (root?.innerText ?? "").replace(/\n$/u, "");
+        }} />
+      </div>
+      <div role="tabpanel" id={`${base}-p0`} aria-labelledby={`${base}-t0`} hidden={tab !== 0}>
+        {code}
+      </div>
+      <div role="tabpanel" id={`${base}-p1`} aria-labelledby={`${base}-t1`} hidden={tab !== 1}>
+        <pre className="code g-diff">
+          <code>
+            {diffLines(diff).map((line, index) => (
+              <span className={`d-${line.kind}`} key={index}>
+                <span className="d-m" aria-hidden="true">{line.mark}</span>
+                {line.body}
+                {line.spoken ? <span className="vh">{line.spoken}</span> : null}
+              </span>
+            ))}
+          </code>
+        </pre>
+      </div>
+    </div>
+  );
+}
+
+function fullscreenElement() {
+  return document.fullscreenElement || (document as Document & { webkitFullscreenElement?: Element }).webkitFullscreenElement || null;
+}
+
+export function FullscreenFrame({ children, label = "演示" }: { children: ReactNode; label?: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const restoreRef = useRef<HTMLElement | null>(null);
+  const [overlay, setOverlay] = useState(false);
+  const [active, setActive] = useState(false);
+
+  useEffect(() => {
+    const onChange = () => {
+      const on = fullscreenElement() === ref.current;
+      setActive(on || overlay);
+      if (!on && !overlay && restoreRef.current) {
+        restoreRef.current.focus();
+        restoreRef.current = null;
+      }
+    };
+    document.addEventListener("fullscreenchange", onChange);
+    document.addEventListener("webkitfullscreenchange", onChange);
+    return () => {
+      document.removeEventListener("fullscreenchange", onChange);
+      document.removeEventListener("webkitfullscreenchange", onChange);
+    };
+  }, [overlay]);
+
+  useEffect(() => {
+    if (!overlay) return undefined;
+    const root = ref.current;
+    document.documentElement.classList.add("ux-lock");
+    const trap = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        setOverlay(false);
+        setActive(false);
+        document.documentElement.classList.remove("ux-lock");
+        restoreRef.current?.focus();
+        return;
+      }
+      if (event.key !== "Tab" || !root) return;
+      const items = [...root.querySelectorAll<HTMLElement>("button, a[href], input, select, textarea, iframe, [tabindex]:not([tabindex='-1'])")]
+        .filter((item) => !item.hasAttribute("disabled") && item.getClientRects().length > 0);
+      if (!items.length) return;
+      const index = items.indexOf(document.activeElement as HTMLElement);
+      const last = items.length - 1;
+      if (index < 0 || (event.shiftKey && index === 0) || (!event.shiftKey && index === last)) {
+        event.preventDefault();
+        items[index < 0 ? 0 : event.shiftKey ? last : 0].focus();
+      }
+    };
+    const pull = (event: FocusEvent) => {
+      if (root && !root.contains(event.target as Node)) buttonRef.current?.focus();
+    };
+    document.addEventListener("keydown", trap, true);
+    document.addEventListener("focusin", pull);
+    buttonRef.current?.focus();
+    return () => {
+      document.documentElement.classList.remove("ux-lock");
+      document.removeEventListener("keydown", trap, true);
+      document.removeEventListener("focusin", pull);
+    };
+  }, [overlay]);
+
+  const open = () => {
+    const node = ref.current;
+    if (!node) return;
+    restoreRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const request = node.requestFullscreen || (node as HTMLElement & { webkitRequestFullscreen?: () => Promise<void> }).webkitRequestFullscreen;
+    if (request && (document.fullscreenEnabled || (document as Document & { webkitFullscreenEnabled?: boolean }).webkitFullscreenEnabled)) {
+      void request.call(node);
+      return;
+    }
+    setOverlay(true);
+    setActive(true);
+  };
+
+  const close = () => {
+    if (fullscreenElement()) {
+      void (document.exitFullscreen?.() || (document as Document & { webkitExitFullscreen?: () => Promise<void> }).webkitExitFullscreen?.());
+      return;
+    }
+    setOverlay(false);
+    setActive(false);
+    restoreRef.current?.focus();
+  };
+
+  return (
+    <div ref={ref} className={`ux-fs${overlay ? " ux-fs-on" : ""}`} role={overlay ? "dialog" : undefined} aria-modal={overlay ? true : undefined} aria-label={overlay ? label : undefined}>
+      <div className="ux-fsbar">
+        <button
+          ref={buttonRef}
+          type="button"
+          className="ux-btn ux-fsb"
+          aria-label={active ? "退出全屏" : "全屏"}
+          title={active ? "退出全屏" : "全屏"}
+          onClick={() => (active ? close() : open())}
+        >
+          {active ? EXIT_ICON : ENTER_ICON}
+        </button>
+      </div>
+      {children}
+    </div>
+  );
+}
+
+const FRAME_BOOT = `<style>
+html,body{background:transparent!important;height:auto!important;min-height:0!important;margin:0;max-width:100%}
+body>*{max-width:100%;box-sizing:border-box}
+svg,img,canvas,video,table{max-width:100%;height:auto}
+#r>style:first-child+*,#r>:first-child:not(style),body>main:first-child>:first-child:not(style){padding-right:44px;box-sizing:border-box}
+</style><script>(function(){
+var last=0,lock=0;
+function fit(){var b=document.body,root=document.documentElement;if(!b)return 1;b.style.zoom="";b.style.transform="";b.style.transformOrigin="";b.style.height="";root.style.height="";var cw=root.clientWidth||b.clientWidth;if(!(cw>0))return 1;var sw=Math.max(root.scrollWidth,b.scrollWidth);if(!(sw>cw+1))return 1;var z=cw/sw;b.style.zoom=String(z);var again=root.scrollWidth;if(again>cw+1&&again<sw-1){z=z*cw/again;b.style.zoom=String(z);again=root.scrollWidth}if(again>cw+1){b.style.zoom="";var h=Math.max(root.scrollHeight,b.scrollHeight);b.style.transformOrigin="0 0";b.style.transform="scale("+z+")";b.style.height=Math.ceil(h*z)+"px";root.style.height=Math.ceil(h*z)+"px"}return z}
+function m(force){if(lock)return;var b=document.body;if(!b)return;lock=1;fit();var h=0,cs=getComputedStyle(b);[].forEach.call(b.children,function(e){if(e.tagName==="SCRIPT"||e.tagName==="STYLE")return;var r=e.getBoundingClientRect(),st=getComputedStyle(e);h=Math.max(h,r.bottom+parseFloat(st.marginBottom||0))});h=Math.ceil(h+parseFloat(cs.paddingBottom||0)+parseFloat(cs.marginBottom||0)+2);if(h>0&&(force||h!==last)){last=h;parent.postMessage({type:"ux:size",height:h,fid:"__UX_FID__"},"*")}lock=0}
+var q=0,pending=0;function s(force){if(force)pending=1;if(q)return;q=1;requestAnimationFrame(function(){q=0;var run=pending;pending=0;m(run)})}
+function watch(){[].forEach.call(document.images||[],function(img){if(img.dataset.uxSized)return;img.dataset.uxSized="1";img.addEventListener("load",s);img.addEventListener("error",s)})}
+var started=0;function boot(){watch();s();if(started||!window.ResizeObserver)return;started=1;var ro=new ResizeObserver(s);ro.observe(document.documentElement);if(document.body)ro.observe(document.body)}
+addEventListener("DOMContentLoaded",boot);addEventListener("load",boot);addEventListener("resize",s);
+var acked=0;
+addEventListener("message",function(e){var d=e.data;if(!d)return;if(d.type==="ux:ack"&&d.fid==="__UX_FID__"){acked=1;return}if(d.type!=="ux:measure"||(d.fid&&d.fid!=="__UX_FID__"))return;last=0;m(1)});
+var tries=0,tick=setInterval(function(){if(acked||++tries>30){clearInterval(tick);return}last=0;m(1)},200);
+setTimeout(function(){last=0;m(1)},0);
+})()<\/script>`;
+
+export function frameSrcdoc(html: string, title: string, fid = "ux") {
+  const csp = `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:;">`;
+  const safe = fid.replace(/[^A-Za-z0-9_-]/g, "") || "ux";
+  const boot = FRAME_BOOT.replaceAll("__UX_FID__", safe);
+  if (/<head[^>]*>/iu.test(html)) return html.replace(/<head[^>]*>/iu, (head) => `${head}${csp}${boot}`);
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>${title}</title>${csp}${boot}</head><body>${html}</body></html>`;
+}
+
+export function SandboxFrame({ html, title }: { html: string; title: string }) {
+  const ref = useRef<HTMLIFrameElement>(null);
+  const [height, setHeight] = useState(80);
+  const fid = useId().replace(/[^A-Za-z0-9_-]/g, "") || "ux";
+  const srcDoc = frameSrcdoc(html, title, fid);
+
+  useEffect(() => {
+    const frame = ref.current;
+    let settled = false;
+    let tries = 0;
+    const ask = () => frame?.contentWindow?.postMessage({ type: "ux:measure", fid }, "*");
+    const onMessage = (event: MessageEvent) => {
+      if (!frame) return;
+      const data = event.data;
+      if (!acceptSandboxSizeMessage(data, fid, event.source, frame.contentWindow)) return;
+      const next = Number(data.height);
+      if (!Number.isFinite(next) || next < 48) return;
+      if (frame.closest(".ux-fs:fullscreen, .ux-fs-on")) return;
+      settled = true;
+      frame.contentWindow?.postMessage({ type: "ux:ack", fid }, "*");
+      setHeight(Math.max(60, Math.min(1600, next)));
+    };
+    window.addEventListener("message", onMessage);
+    frame?.addEventListener("load", ask);
+    ask();
+    const timer = window.setInterval(() => {
+      if (settled || tries++ > 30) {
+        window.clearInterval(timer);
+        return;
+      }
+      ask();
+    }, 200);
+    return () => {
+      window.clearInterval(timer);
+      window.removeEventListener("message", onMessage);
+      frame?.removeEventListener("load", ask);
+    };
+  }, [fid]);
+
+  return (
+    <FullscreenFrame label={title}>
+      <div className="g-sandbox">
+        <iframe
+          ref={ref}
+          title={title}
+          sandbox="allow-scripts"
+          referrerPolicy="no-referrer"
+          srcDoc={srcDoc}
+          style={{ height, overflow: "hidden", background: "transparent" }}
+        />
+      </div>
+    </FullscreenFrame>
+  );
+}

package/app/components/garden/sandbox-message.ts

@@ -0,0 +1,16 @@
+export type SandboxSizeData = {
+  type?: string;
+  fid?: string;
+  height?: unknown;
+};
+
+/** A resize is from this frame only when both the window and the frame id match. */
+export function acceptSandboxSizeMessage(
+  data: SandboxSizeData | null | undefined,
+  fid: string,
+  source: unknown,
+  contentWindow: unknown,
+): boolean {
+  if (!data || (data.type !== "ux:size" && data.type !== "garden:resize")) return false;
+  return contentWindow != null && source === contentWindow && data.fid === fid;
+}

package/app/garden-modules.d.ts

@@ -34,6 +34,7 @@ declare module "@garden/generated-content" {
     columnCoverAlt?: string;
     order?: number;
     cover?: string;
+    original?: string;
     mediaType?: "image" | "audio" | "video" | "link" | "text";
     media?: string | MediaItem[];
     mediaAlt?: string;
@@ -46,6 +47,7 @@ declare module "@garden/generated-content" {
   export const posts: ContentEntry[];
   export const columns: ContentEntry[];
   export const thoughts: ContentEntry[];
+  export const a2WordCounts: Record<string, number>;
 }
 
 declare module "@garden/site-config" {

package/app/globals.css

@@ -3761,27 +3761,32 @@ button {
   .toc-mobile-trigger {
     position: fixed;
     right: calc(16px + env(safe-area-inset-right));
-    bottom: calc(14px + env(safe-area-inset-bottom));
+    bottom: calc(16px + env(safe-area-inset-bottom));
     z-index: 70;
-    min-height: 42px;
-    padding: 0 15px;
+    min-height: 44px;
+    padding: 0 18px 0 15px;
     display: inline-flex;
     align-items: center;
     gap: 8px;
-    border: 1px solid color-mix(in srgb, var(--paper) 15%, transparent);
+    border: 1px solid #d9d5cc;
     border-radius: 999px;
-    background: color-mix(in srgb, var(--ink) 94%, transparent);
-    box-shadow: 0 10px 30px rgb(0 0 0 / 20%);
-    color: var(--paper);
-    font-size: 12px;
-    font-weight: 700;
-    letter-spacing: 0.05em;
-    backdrop-filter: blur(12px);
-    -webkit-backdrop-filter: blur(12px);
+    background: rgb(255 255 255 / 94%);
+    box-shadow: 0 2px 10px rgb(27 26 24 / 10%);
+    color: var(--ink);
+    font: 600 14px/1 var(--sans);
+    letter-spacing: 0;
     touch-action: manipulation;
+    cursor: pointer;
     transition: opacity 160ms ease, transform 160ms ease, visibility 0s;
   }
 
+  :root[data-theme="dark"] .toc-mobile-trigger,
+  html[data-theme="dark"] .toc-mobile-trigger {
+    background: rgb(30 29 26 / 94%);
+    border-color: var(--rule-strong);
+    color: var(--ink);
+  }
+
   .toc-mobile-trigger:hover,
   .toc-mobile-trigger:focus-visible {
     transform: translateY(-2px);

package/app/layout.tsx

@@ -2,6 +2,9 @@ import type { Metadata } from "next";
 import { Geist_Mono } from "next/font/google";
 import "katex/dist/katex.min.css";
 import "./globals.css";
+import "./styles/tokens.css";
+import "./styles/a2.css";
+import "./styles/shell.css";
 import { SiteChrome } from "./components/SiteChrome";
 import {
   getSiteUrl,
@@ -82,6 +85,12 @@ export default function RootLayout({
   return (
     <html lang="zh-CN" suppressHydrationWarning>
       <head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              '(function(){try{var t=localStorage.getItem("theme");var d=t==="dark"||(!t&&matchMedia("(prefers-color-scheme: dark)").matches);document.documentElement.dataset.theme=d?"dark":"light";}catch(e){}})();',
+          }}
+        />
         {mentionEndpoint && <link rel="webmention" href={mentionEndpoint} />}
         {analyticsDomain && (
           <script

package/app/lib/a2-meta.ts

@@ -0,0 +1,22 @@
+const shanghaiOffsetMs = 8 * 60 * 60 * 1000;
+
+function shanghaiDate(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return new Date(date.getTime() + shanghaiOffsetMs);
+}
+
+/** Calendar date in Asia/Shanghai, the zone the demo uses for 「2026 年 9 月 18 日」. */
+export function demoDateLabel(value: string) {
+  const date = shanghaiDate(value);
+  if (!date) return value;
+  return `${date.getUTCFullYear()} 年 ${date.getUTCMonth() + 1} 月 ${date.getUTCDate()} 日`;
+}
+
+export function demoDateTime(value: string) {
+  const date = shanghaiDate(value);
+  if (!date) return value.slice(0, 10);
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${date.getUTCFullYear()}-${month}-${day}`;
+}

package/app/lib/a2-preview.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+
+const dir = path.join(process.cwd(), "parity", "articles");
+
+const originals: Record<string, string> = {
+  "ai-agent-react-vs-workflow": "https://hedon.top/blog/ai-agent/ai-agent-react-vs-workflow/",
+  "rust-action-spinlock": "https://hedon.top/blog/rust-action-spinlock/",
+  "claude-code-source": "https://hedon.top/blog/claude-code-source/",
+  "go-gc-tri-color-marking": "https://hedon.top/blog/go/go-gc-tri-color-marking/",
+  "kv-cache-interactive": "https://hedon.top/blog/llm-kv-cache/",
+};
+
+export type A2Article = {
+  slug: string;
+  title: string;
+  description: string;
+  date: string;
+  topic: string;
+  cover: string;
+  original: string;
+  content: string;
+};
+
+export function a2Slugs() {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -3)).sort();
+}
+
+export function readA2Article(slug: string): A2Article | null {
+  const file = path.join(dir, `${slug}.md`);
+  if (!fs.existsSync(file)) return null;
+  const parsed = matter(fs.readFileSync(file, "utf8"));
+  const data = parsed.data ?? {};
+  const cover = typeof data.cover === "string" ? data.cover : "";
+  const date = data.date instanceof Date && !Number.isNaN(data.date.getTime())
+    ? data.date.toISOString()
+    : typeof data.date === "string" ? data.date : "";
+  return {
+    slug,
+    title: String(data.title ?? slug),
+    description: String(data.description ?? ""),
+    date,
+    topic: String(data.topic ?? ""),
+    cover: cover && !/^https?:/iu.test(cover) ? `https://hedon.top/media/covers/${cover}` : cover,
+    original: originals[slug] ?? "",
+    content: parsed.content,
+  };
+}

package/app/lib/content.ts

@@ -8,6 +8,7 @@ import {
 } from "@garden/generated-content";
 import GithubSlugger from "github-slugger";
 import { canonicalSiteDate } from "../../scripts/site-date.mjs";
+import { demoDateLabel } from "./a2-meta";
 import { contentToSearchText } from "../../ui/core/transform.mjs";
 import { toString } from "mdast-util-to-string";
 import remarkParse from "remark-parse";
@@ -26,6 +27,7 @@ export const columnHref = (entry: Pick<ContentEntry, "column" | "path">) =>
   `/columns/${entry.column}/${columnEntryPath(entry)}`;
 
 export const formatDate = (value: string, withTime = false) => {
+  if (!withTime) return demoDateLabel(value);
   const canonical = canonicalSiteDate(value) ?? value;
   const date = new Date(canonical);
   if (Number.isNaN(date.getTime())) return value;
@@ -34,26 +36,70 @@ export const formatDate = (value: string, withTime = false) => {
     year: "numeric",
     month: "2-digit",
     day: "2-digit",
-    ...(withTime ? { hour: "2-digit", minute: "2-digit" } : {}),
+    hour: "2-digit",
+    minute: "2-digit",
   }).format(date);
 };
 
+const NUMBERED_ARTICLE = /^#{2,3}[ \t]+\d/m;
+
+/** An article that already writes its own heading numbers is not auto-numbered. */
+export const articleUsesHeadingNumbers = (markdown: string) => NUMBERED_ARTICLE.test(markdown);
+
+/**
+ * Prototype render: an article with no `##` treats `###` as the top section.
+ * Display level is `depth - base + 2`, and anything past h3 stays an h4.
+ */
+export const articleHeadingBase = (markdown: string) => (/^##[ \t]/m.test(markdown) ? 2 : 3);
+
+export const displayHeadingLevel = (depth: number, base: number) => {
+  if (depth < 2 || depth > 4) return depth;
+  const level = depth - base + 2;
+  return level > 3 ? 4 : level;
+};
+
+/** Pull a leading `2.1` into the section marker and leave the heading sentence. */
+export const splitHeadingNumber = (text: string) => {
+  const match = /^(\d+(?:\.\d+)*)\.?[ \t]+([\s\S]+)$/u.exec(text.trim());
+  return match ? { no: match[1], text: match[2] } : null;
+};
+
 /**
  * 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.
  */
 export const extractHeadings = (markdown: string) => {
   const slugger = new GithubSlugger();
-  const headings: Array<{ depth: number; text: string; id: string }> = [];
+  const numbered = articleUsesHeadingNumbers(markdown);
+  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 text = toString(node).trim();
-    const id = slugger.slug(text);
-    if (text && node.depth >= 2 && node.depth <= 5) {
-      headings.push({ depth: node.depth, text, id });
+    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 (!numbered) {
+        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 } : {}) });
   });
 
   return headings;

package/app/lib/markdown-plugins.ts

@@ -3,6 +3,7 @@ import remarkCjkFriendly from "remark-cjk-friendly";
 import remarkBreaks from "remark-breaks";
 import remarkMath from "remark-math";
 import type { PluggableList } from "unified";
+import { remarkGarden } from "./remark-garden.mjs";
 
 // Keep article rendering and heading extraction on the same Markdown syntax.
 export const markdownPlugins: PluggableList = [
@@ -10,4 +11,5 @@ export const markdownPlugins: PluggableList = [
   remarkCjkFriendly,
   remarkBreaks,
   remarkMath,
+  remarkGarden,
 ];