hd-garden 0.10.2 → 0.10.3

package/README.en.md

@@ -44,7 +44,17 @@ npx garden ui check --staged                    # Check staged posts for uncompi
 npx garden ui catalog                           # Generate an offline component gallery at .garden/ui-catalog.html
 ```
 
-## 4. Handbook and reference docs
+## 4. Excalidraw
+
+Point a Markdown image at the `.excalidraw` source. `garden build` exports one light flat SVG beside that file, with a transparent background, and embeds that SVG in the article so its text can be selected. No separate export command.
+
+```markdown
+![A sketch](./assets/flow.excalidraw)
+```
+
+The first page that references `.excalidraw` downloads the exporter (Chromium is not required; fonts are embedded in the SVG). See [Local Image](docs/handbook/en/components/image.md).
+
+## 5. Handbook and reference docs
 
 Start `make dev` and open `/garden/en` (Chinese at `/garden`), or read the markdown sources directly:
 

package/README.md

@@ -46,7 +46,17 @@ npx garden ui check --staged                   # 检查暂存区稿件中的想
 npx garden ui catalog                          # 在 .garden/ui-catalog.html 生成离线组件清单
 ```
 
-## 4. 使用说明与深入文档
+## 4. Excalidraw
+
+正文用 Markdown 图片指向 `.excalidraw` 源文件。`garden build` 会在同目录导出一张浅色扁平 SVG，画布背景透明，并把这张 SVG 嵌进正文，图里的文字可以选中。不需要单独的导出命令。
+
+```markdown
+![说明](./assets/flow.excalidraw)
+```
+
+页面里第一次出现 `.excalidraw` 时，构建会下载导出程序（不需要 Chromium；字体写进 SVG）。说明见[本地图片](docs/handbook/components/image.md)。
+
+## 5. 使用说明与深入文档
 
 本地运行 `make dev` 后访问 `/garden`（英文版在 `/garden/en`），或直接阅读仓库内的文档：
 

package/app/components/ArticleMeasure.tsx

@@ -137,7 +137,7 @@ export function ArticleMeasure() {
       });
       // Images: as wide as they display (2x screenshots at half their pixels), up to 1040px in total.
       article.querySelectorAll<HTMLElement>(".fig").forEach((figure) => {
-        const image = figure.querySelector("img");
+        const image = figure.querySelector<HTMLImageElement>("img, svg.excalidraw");
         resetWide(figure);
         // From here on the browser decides; the build-time breakout CSS steps aside.
         figure.classList.remove("fig-wide");
@@ -148,8 +148,9 @@ export function ArticleMeasure() {
         if (baseWidth) image.style.width = `${baseWidth}px`;
         else image.style.removeProperty("width");
         // Sizes read at build time let this run before the file arrives; otherwise wait for load.
+        // An inline Excalidraw SVG has no naturalWidth; its width attribute is the scene size.
         const known = Number(image.dataset.nw) || 0;
-        const pixels = image.naturalWidth || known;
+        const pixels = image.naturalWidth || known || Number(image.getAttribute("width")) || 0;
         if (!pixels) return;
         // width="" written by the build is the pixel size, not an author's choice.
         const attrWidth = known ? Number(image.dataset.aw) || 0 : Number(image.getAttribute("width")) || 0;

package/app/styles/a2.css

@@ -720,6 +720,19 @@ html[data-theme="dark"] .markdown-body > p > img:not([class]) {
   border-radius: 8px;
 }
 
+.markdown-body .fig-card > svg.excalidraw,
+.markdown-body svg.excalidraw {
+  display: block;
+  width: auto;
+  max-width: 100%;
+  height: auto;
+  margin: 0 auto;
+}
+
+.markdown-body svg.excalidraw text {
+  user-select: text;
+}
+
 .markdown-body .fig figcaption {
   margin-top: 12px;
   font-size: var(--fs-small);

package/docs/handbook/components/image.md

@@ -23,4 +23,14 @@ order: 45
 
 随想里的图片写在 Front Matter 的 `media` 中，多张拼成宫格，不使用这套图注。见[写文章与随想](/garden/writing)。
 
+## Excalidraw
+
+`.excalidraw` 和别的配图放在一起。正文仍用 Markdown 图片，地址指向源文件，例如 `./my-post/flow.excalidraw`。没有单独的 garden 组件。
+
+`garden build`、`make dev` 和 `garden sync` 会找出这些图片。源文件有改动，或旁边的 `.svg` 缺失、过期时，先删掉旧的 `.svg`，再导出一张新的扁平 SVG，里面不嵌可再编辑的场景。上面的例子会得到同目录的 `flow.svg`。只这一张浅色 SVG：画布背景透明，场景里的线条和填色保持绘制时的样子，不另出深色文件，也不做 CSS 反色。页面把这张 SVG 嵌进正文，图里的文字可以选中复制；说明写在 SVG 的 `title` 里。文章脚本不会加载 Excalidraw。
+
+导出程序是 [excalidraw-image](https://github.com/rickardp/excalidraw-image) `0.2.0`，走的是 Excalidraw 自己的 SVG 导出。第一次遇到 `.excalidraw` 时，构建从 GitHub Releases 下载对应系统的可执行文件（压缩包约 48MB）并缓存在本机。不需要安装 Chromium。字体写进 SVG，页面不请求 excalidraw.com。已经下载过，或用 `GARDEN_EXCALIDRAW_IMAGE` 指向本机程序时，离线构建（`GARDEN_OFFLINE` 设为 `1`）不会再次下载。
+
+源文件缺失，或导出失败时，构建直接停止，并写明路径和原因。
+
 这不是 `garden` 围栏，没有字段表。

package/docs/handbook/en/components/image.md

@@ -23,4 +23,14 @@ The caption under this figure is its alt text:
 
 Images on a thought go in the `media` list in Front Matter and form a grid, without this caption. See [Writing Posts & Thoughts](/garden/en/writing).
 
+## Excalidraw
+
+Put the `.excalidraw` file with the post's other images. Keep using a Markdown image, and point the address at the source file, for example `./my-post/flow.excalidraw`. There is no separate garden component for this.
+
+`garden build`, `make dev`, and `garden sync` find those images. When the source has changed, or the sibling `.svg` is missing or out of date, the old `.svg` is deleted and a new flat SVG is exported, with no editable scene embedded. The example above produces `flow.svg` in the same directory. That is the only export: one light SVG with a transparent canvas. Strokes and fills stay as drawn. There is no dark file and no CSS invert. The page embeds that SVG in the article, so the text in the figure can be selected and copied. The alt text is the SVG `title`. The article never loads Excalidraw.
+
+The exporter is [excalidraw-image](https://github.com/rickardp/excalidraw-image) `0.2.0`, which runs Excalidraw's own SVG export. The first `.excalidraw` reference downloads the matching executable from GitHub Releases (about 48 MB compressed) and caches it on the machine. Chromium is not required. Fonts are written into the SVG, so the page does not request excalidraw.com. After that download, or when `GARDEN_EXCALIDRAW_IMAGE` points at a local binary, an offline build (`GARDEN_OFFLINE` set to `1`) does not download again.
+
+A missing source file or a failed export stops the build and reports the path and the reason.
+
 This is not a `garden` fence, so it has no field table.

package/docs/handbook/en/writing.md

@@ -115,6 +115,7 @@ func openStore(path string) (*Store, error) {
 These three are written in the Markdown body. Rendering rules live on the component pages. This section only records where the files go:
 
 - **Local images**: For a post at `content/posts/my-post.md`, put images in `content/posts/my-post/` and reference them as `./my-post/diagram.svg`. Captions are documented on [Local Image](/garden/en/components/image).
+- **Excalidraw**: Put the source with the other images and reference it with a Markdown image whose address ends in `.excalidraw`, for example `./my-post/flow.excalidraw`. The build writes one light `flow.svg` beside it, with a transparent background, and embeds that SVG in the article so its text can be selected. See [Local Image](/garden/en/components/image).
 - **Source chips** and **link cards** stay in the prose. See [Source Chip](/garden/en/components/source) and [Link Card](/garden/en/components/link-card).
 
 ## 5. Math Formulas and Mermaid Diagrams

package/docs/handbook/writing.md

@@ -115,6 +115,7 @@ func openStore(path string) (*Store, error) {
 这三项写在 Markdown 正文里。渲染规则在组件页，这里只保留文件放哪：
 
 - **本地图片**：长文 `content/posts/my-post.md` 的配图放在同名目录 `content/posts/my-post/`，正文用 `./my-post/diagram.svg` 引用。图注见[本地图片](/garden/components/image)。
+- **Excalidraw**：源文件和配图放在一起，用 Markdown 图片引用，地址以 `.excalidraw` 结尾，例如 `./my-post/flow.excalidraw`。构建生成旁边的一张浅色 `flow.svg`，画布背景透明，并把 SVG 嵌进正文，图里的文字可以选中。见[本地图片](/garden/components/image)。
 - **来源胶囊**与**链接卡片**不另建文件。见[来源胶囊](/garden/components/source)和[链接卡片](/garden/components/link-card)。
 
 ## 5. 数学公式与 Mermaid 图表

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",

package/scripts/build-content.mjs

@@ -19,6 +19,8 @@ import { buildFullIndex, buildSearchIndex } from "../ui/garden/search-index.mjs"
 import { coverImageSet, loadSharp } from "./cover-images.mjs";
 import { readFileSizeCache } from "./file-sizes.mjs";
 import { previewDocument, previewFileName, renderFilePreview } from "./file-preview.mjs";
+import { ensureExcalidrawSvg, isExcalidrawPath } from "./excalidraw.mjs";
+import { embedExcalidrawImages, embedExcalidrawImgTags } from "../ui/garden/excalidraw-inline.mjs";
 import { parseGardenBlock, parseGardenInfo, scanFences } from "../ui/garden/parse.mjs";
 import { checkGardenMarkdown } from "../ui/garden/check.mjs";
 import {
@@ -152,23 +154,40 @@ const assetCache = new Map();
 /** Published URL → original file and its copy, for making resized covers later. */
 const assetFiles = new Map();
 
-function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
-  if (!value || isExternalAsset(value)) return value;
-
+function locateLocalAsset(value, markdownPath, sourcePath, options = {}) {
+  if (!value || isExternalAsset(value)) return null;
   const baseDir = options.baseDir ?? path.dirname(markdownPath);
   const allowedRoot = options.allowedRoot ?? contentRoot;
-  const mediaPrefix = options.mediaPrefix ?? "";
   const [assetPath, suffix = ""] = value.split(/(?=[?#])/u, 2);
   const decodedPath = decodeURIComponent(assetPath.replace(/^<|>$/g, ""));
   const absoluteSource = path.resolve(baseDir, decodedPath);
   const relativeSource = path.relative(allowedRoot, absoluteSource);
+  if (relativeSource.startsWith("..") || path.isAbsolute(relativeSource)) {
+    fail(sourcePath, options.missingMessage ?? `找不到本地媒体文件 ${value}`);
+  }
+  return { absoluteSource, relativeSource, decodedPath, suffix, mediaPrefix: options.mediaPrefix ?? "" };
+}
 
-  if (
-    relativeSource.startsWith("..") ||
-    path.isAbsolute(relativeSource) ||
-    !fs.existsSync(absoluteSource) ||
-    !fs.statSync(absoluteSource).isFile()
-  ) {
+/** Export the sibling flat SVG and return its text. The page inlines this; it is not an image URL. */
+function readExportedSvg(value, markdownPath, sourcePath, options = {}) {
+  const located = locateLocalAsset(value, markdownPath, sourcePath, options);
+  if (!located || !isExcalidrawPath(located.decodedPath)) {
+    fail(sourcePath, `找不到 Excalidraw 源文件 ${value}`);
+  }
+  try {
+    const svgPath = ensureExcalidrawSvg(located.absoluteSource);
+    return fs.readFileSync(svgPath, "utf8");
+  } catch (error) {
+    fail(sourcePath, error instanceof Error ? error.message : String(error));
+  }
+}
+
+function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
+  const located = locateLocalAsset(value, markdownPath, sourcePath, options);
+  if (!located) return value;
+  const { absoluteSource, relativeSource, suffix, mediaPrefix } = located;
+
+  if (!fs.existsSync(absoluteSource) || !fs.statSync(absoluteSource).isFile()) {
     fail(sourcePath, options.missingMessage ?? `找不到本地媒体文件 ${value}`);
   }
 
@@ -194,15 +213,21 @@ function copyLocalAsset(value, markdownPath, sourcePath, options = {}) {
 function rewriteMarkdownAssets(content, markdownPath, sourcePath, options = {}) {
   // `![alt](<a b (1).png>)` keeps its angle brackets: without them the space
   // and the parentheses would no longer be one destination.
-  const markdownImages = replaceInlineLinks(content, (link) =>
-    link.image ? formatInlineLink(link, copyLocalAsset(link.url, markdownPath, sourcePath, options)) : undefined,
-  );
+  // `.excalidraw` images stay in the source until the AST embed below, which
+  // swaps them for the inline SVG instead of an image URL.
+  const markdownImages = replaceInlineLinks(content, (link) => {
+    if (!link.image || isExcalidrawPath(link.url)) return undefined;
+    return formatInlineLink(link, copyLocalAsset(link.url, markdownPath, sourcePath, options));
+  });
 
-  return markdownImages.replace(
+  const withAssets = markdownImages.replace(
     /(<(?:img|audio|video|source)\b[^>]*\bsrc=["'])([^"']+)(["'])/giu,
-    (_, prefix, src, suffix) =>
-      `${prefix}${copyLocalAsset(src, markdownPath, sourcePath, options)}${suffix}`,
+    (tag, prefix, src, suffix) =>
+      isExcalidrawPath(src) ? tag : `${prefix}${copyLocalAsset(src, markdownPath, sourcePath, options)}${suffix}`,
   );
+
+  const read = (url) => readExportedSvg(url, markdownPath, sourcePath, options);
+  return embedExcalidrawImgTags(embedExcalidrawImages(withAssets, read), read);
 }
 
 function markdownStem(markdownPath) {

package/scripts/excalidraw.mjs

@@ -0,0 +1,372 @@
+/**
+ * Build-time export of `.excalidraw` scenes to a sibling flat SVG.
+ *
+ * Authors reference the source (`![说明](./assets/foo.excalidraw)`). Content
+ * sync calls `ensureExcalidrawSvg`, which deletes a missing or stale sibling
+ * `foo.svg` and writes a new one. The SVG is what gets published.
+ *
+ * Rendering goes through the pinned `excalidraw-image` binary (the official
+ * `@excalidraw/excalidraw` export path, fonts inlined as data URIs). One light
+ * SVG is written: `--no-background` drops the canvas plate, and scene strokes
+ * and fills stay as drawn. There is no dark twin and no Chromium step. The
+ * article bundle never loads Excalidraw. The first export downloads that
+ * binary from GitHub Releases into the user cache.
+ * `GARDEN_EXCALIDRAW_IMAGE` points at a local binary instead.
+ * `GARDEN_OFFLINE=1` refuses to download.
+ */
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const EXCALIDRAW_IMAGE_VERSION = "0.2.0";
+
+const RELEASE_BASE = `https://github.com/rickardp/excalidraw-image/releases/download/v${EXCALIDRAW_IMAGE_VERSION}`;
+
+/** @type {Record<string, { file: string, sha256: string }>} */
+const ASSETS = {
+  "darwin-arm64": {
+    file: "excalidraw-image-aarch64-apple-darwin.tar.gz",
+    sha256: "387f7ef44a75528e4c6cca9f0af4bba34e017986f34581d983bb2a96afb5d9ba",
+  },
+  "darwin-x64": {
+    file: "excalidraw-image-x86_64-apple-darwin.tar.gz",
+    sha256: "bef1198f6237123ecc7f63c1fc6a456413e5f6cc91ae4c548dc26d661066fc21",
+  },
+  "linux-arm64": {
+    file: "excalidraw-image-aarch64-unknown-linux-gnu.tar.gz",
+    sha256: "c6b222e128965568e281af96edfa437393b2ddb4e3ba360ec2b9b583f273143e",
+  },
+  "linux-x64": {
+    file: "excalidraw-image-x86_64-unknown-linux-gnu.tar.gz",
+    sha256: "6a86f5188b55aef092d9cedda786565bfdb399bb58e57a1bea26335ed8f19ac6",
+  },
+  "win32-x64": {
+    file: "excalidraw-image-x86_64-pc-windows-msvc.zip",
+    sha256: "19b387b2322d3b52f8003d2e8bea9ab5693086c5886986f86b5ac6c36009aeef",
+  },
+};
+
+const REASONS = {
+  "missing-source": "找不到 Excalidraw 源文件",
+  "export-failed": "导出 Excalidraw 失败",
+  offline: "离线构建找不到 excalidraw-image",
+  "download-failed": "下载 excalidraw-image 失败",
+  checksum: "excalidraw-image 校验和不匹配",
+  "embedded-scene": "导出的 SVG 仍包含可编辑场景",
+  "remote-asset": "导出的 SVG 引用了外部地址",
+  "not-svg": "导出结果不是 SVG",
+  "canvas-background": "导出的 SVG 仍带画布底色",
+  "unsupported-platform": "当前系统没有 excalidraw-image 预编译包",
+  "binary-missing": "GARDEN_EXCALIDRAW_IMAGE 指向的文件不存在",
+  "no-output": "导出程序没有写出 SVG",
+};
+
+const EXPORT_POLICY = "light-transparent";
+const STAMP = /<!--\s*garden-excalidraw-source:([0-9a-f]{64})(?:\s+([a-z0-9-]+))?\s*-->/u;
+const LOCK_WAIT_MS = 5 * 60 * 1000;
+
+export class ExcalidrawExportError extends Error {
+  /**
+   * @param {keyof typeof REASONS} code
+   * @param {string} message
+   * @param {string} file
+   */
+  constructor(code, message, file) {
+    super(message);
+    this.name = "ExcalidrawExportError";
+    this.code = code;
+    this.file = file;
+  }
+}
+
+/**
+ * @param {keyof typeof REASONS} code
+ * @param {string} file
+ * @param {string} [detail]
+ */
+function failExport(code, file, detail) {
+  const lead = REASONS[code];
+  if (!lead) {
+    const unknown = /** @type {never} */ (code);
+    throw new Error(`未知的 Excalidraw 错误码 ${unknown}`);
+  }
+  const tail = detail ? `（${detail}）` : "";
+  return new ExcalidrawExportError(code, `[excalidraw:${code}] ${lead} ${file}${tail}`, file);
+}
+
+/** sha256 of the `.excalidraw` bytes. Any edit changes the stamp. */
+export function sourceHash(contents) {
+  return crypto.createHash("sha256").update(contents).digest("hex");
+}
+
+/** `flow.excalidraw` → `flow.svg` beside it. The extension match is case-insensitive. */
+export function siblingSvgPath(excalidrawPath) {
+  return String(excalidrawPath).replace(/\.excalidraw$/iu, ".svg");
+}
+
+/** True for a Markdown path whose file is an `.excalidraw` source, not an `.excalidraw.svg`. */
+export function isExcalidrawPath(value) {
+  const clean = String(value ?? "").split(/[?#]/u, 1)[0];
+  return /\.excalidraw$/iu.test(clean);
+}
+
+function stampSvg(svg, hash) {
+  const stripped = svg.replace(/<!--\s*garden-excalidraw-source:[0-9a-f]{64}(?:\s+[a-z0-9-]+)?\s*-->/gu, "");
+  const at = stripped.search(/<svg[\s>]/iu);
+  if (at < 0) throw failExport("not-svg", "");
+  return `${stripped.slice(0, at)}<!-- garden-excalidraw-source:${hash} ${EXPORT_POLICY} -->${stripped.slice(at)}`;
+}
+
+/** A full-viewport `<rect>` is the exporter's canvas plate, not a scene shape. */
+function hasCanvasBackground(svg) {
+  const svgTag = /<svg\b[^>]*>/iu.exec(svg)?.[0] ?? "";
+  const attr = (tag, name) => new RegExp(`\\b${name}="([^"]*)"`, "iu").exec(tag)?.[1];
+  const width = Number(attr(svgTag, "width"));
+  const height = Number(attr(svgTag, "height"));
+  if (!(width > 0) || !(height > 0)) return false;
+  const same = (left, right) => Math.abs(left - right) < 0.01;
+  for (const match of svg.matchAll(/<rect\b[^>]*>/giu)) {
+    const tag = match[0];
+    const x = Number(attr(tag, "x") ?? 0);
+    const y = Number(attr(tag, "y") ?? 0);
+    const rectWidth = Number(attr(tag, "width"));
+    const rectHeight = Number(attr(tag, "height"));
+    if (same(x, 0) && same(y, 0) && same(rectWidth, width) && same(rectHeight, height)) return true;
+  }
+  return false;
+}
+
+/**
+ * A published figure must be a flat SVG: no embedded scene, no host the
+ * reader's browser would have to call.
+ * @param {string} svg
+ * @param {string} svgPath
+ */
+function assertFlatSvg(svg, svgPath) {
+  if (!/<svg[\s>]/iu.test(svg)) throw failExport("not-svg", svgPath);
+  if (/payload-start|application\/vnd\.excalidraw\+json/iu.test(svg)) {
+    throw failExport("embedded-scene", svgPath);
+  }
+  if (hasCanvasBackground(svg)) throw failExport("canvas-background", svgPath);
+  const urls = [...svg.matchAll(/https?:\/\/[^"')\s]+/giu)]
+    .map((match) => match[0])
+    .filter((url) => !/^https?:\/\/www\.w3\.org\//iu.test(url));
+  if (urls.length) throw failExport("remote-asset", svgPath, urls.slice(0, 3).join(" "));
+}
+
+function svgIsCurrent(svg, hash) {
+  const stamp = STAMP.exec(svg);
+  if (!stamp || stamp[1] !== hash || stamp[2] !== EXPORT_POLICY) return false;
+  try {
+    assertFlatSvg(svg, "");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function platformAsset() {
+  const asset = ASSETS[platformKey()];
+  if (!asset) {
+    throw failExport(
+      "unsupported-platform",
+      `${process.platform} ${process.arch}`,
+      "设置 GARDEN_EXCALIDRAW_IMAGE 指向本机的 excalidraw-image",
+    );
+  }
+  return asset;
+}
+
+/**
+ * @param {{ homedir?: string }} [options]
+ */
+function cachePath(options = {}) {
+  const home = options.homedir ?? os.homedir();
+  const exe = process.platform === "win32" ? "excalidraw-image.exe" : "excalidraw-image";
+  return path.join(home, ".cache", "garden", "excalidraw-image", EXCALIDRAW_IMAGE_VERSION, platformKey(), exe);
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withLock(lockDir, fn) {
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      fs.mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      let stale = false;
+      try {
+        stale = Date.now() - fs.statSync(lockDir).mtimeMs > LOCK_WAIT_MS;
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        fs.rmSync(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) throw failExport("download-failed", lockDir, "等待下载锁超时");
+      sleep(100);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    fs.rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function run(command, args, { timeout = 120_000 } = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    timeout,
+    maxBuffer: 32 * 1024 * 1024,
+    windowsHide: true,
+  });
+}
+
+function commandFailure(result, fallback) {
+  if (result.error) return result.error.message;
+  return (result.stderr || result.stdout || fallback).trim();
+}
+
+function findExportedBinary(dir) {
+  const names = new Set(["excalidraw-image", "excalidraw-image.exe"]);
+  const found = [];
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    if (!current) break;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (names.has(entry.name)) found.push(full);
+    }
+  }
+  if (found.length !== 1) {
+    throw failExport("download-failed", dir, `压缩包里应有一个 excalidraw-image，实际 ${found.length} 个`);
+  }
+  return found[0];
+}
+
+/**
+ * @param {{ homedir?: string, env?: NodeJS.ProcessEnv }} options
+ */
+function installBinary(options) {
+  const asset = platformAsset();
+  const cached = cachePath(options);
+  return withLock(`${cached}.lock`, () => {
+    if (fs.existsSync(cached)) return cached;
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "garden-excalidraw-"));
+    try {
+      const archive = path.join(work, asset.file);
+      const url = `${RELEASE_BASE}/${asset.file}`;
+      console.error(`正在下载 excalidraw-image ${EXCALIDRAW_IMAGE_VERSION}（${asset.file}）…`);
+      const curl = run("curl", ["-fsSL", "--retry", "3", "--retry-delay", "2", "-o", archive, url]);
+      if (curl.status !== 0) throw failExport("download-failed", url, commandFailure(curl, "curl 失败"));
+      const got = crypto.createHash("sha256").update(fs.readFileSync(archive)).digest("hex");
+      if (got !== asset.sha256) throw failExport("checksum", asset.file, `期望 ${asset.sha256}，实际 ${got}`);
+      const unpacked = path.join(work, "unpacked");
+      fs.mkdirSync(unpacked, { recursive: true });
+      const extracted = run("tar", ["-xf", archive, "-C", unpacked]);
+      if (extracted.status !== 0) {
+        throw failExport("download-failed", archive, commandFailure(extracted, "tar 无法解压"));
+      }
+      const bin = findExportedBinary(unpacked);
+      fs.mkdirSync(path.dirname(cached), { recursive: true });
+      const partial = `${cached}.partial`;
+      fs.copyFileSync(bin, partial);
+      fs.chmodSync(partial, 0o755);
+      const version = run(partial, ["--version"]);
+      if (version.status !== 0 || !/excalidraw-image/u.test(version.stdout || "")) {
+        fs.rmSync(partial, { force: true });
+        throw failExport("download-failed", partial, commandFailure(version, "excalidraw-image --version 失败"));
+      }
+      fs.renameSync(partial, cached);
+      return cached;
+    } finally {
+      fs.rmSync(work, { recursive: true, force: true });
+    }
+  });
+}
+
+/**
+ * @param {{ homedir?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+function resolveBinary(options = {}) {
+  const env = options.env ?? process.env;
+  const override = env.GARDEN_EXCALIDRAW_IMAGE?.trim();
+  if (override) {
+    if (!fs.existsSync(override)) throw failExport("binary-missing", override);
+    return override;
+  }
+  platformAsset();
+  const cached = cachePath(options);
+  if (fs.existsSync(cached)) return cached;
+  if (env.GARDEN_OFFLINE === "1") throw failExport("offline", cached);
+  return installBinary(options);
+}
+
+let defaultBinary = "";
+
+/**
+ * @param {string} input
+ * @param {string} output
+ * @param {{ homedir?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+function renderWithBinary(input, output, options = {}) {
+  const custom = options.env !== undefined || options.homedir !== undefined;
+  const bin = !custom && defaultBinary && fs.existsSync(defaultBinary) ? defaultBinary : resolveBinary(options);
+  if (!custom) defaultBinary = bin;
+  const result = run(bin, [input, "--non-editable", "--no-background", "--format", "svg", "-o", output]);
+  if (result.status !== 0) {
+    throw failExport("export-failed", input, commandFailure(result, `退出码 ${result.status}`).slice(0, 800));
+  }
+}
+
+/**
+ * Write a current flat SVG next to `sourcePath`.
+ * A sibling SVG is reused only when it carries this source's hash and is flat.
+ * Otherwise it is deleted, then exported again. Export failure leaves no SVG.
+ *
+ * @param {string} sourcePath
+ * @param {{ render?: (input: string, output: string) => void, homedir?: string, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {string} absolute path of the sibling SVG
+ */
+export function ensureExcalidrawSvg(sourcePath, options = {}) {
+  if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile()) {
+    throw failExport("missing-source", sourcePath);
+  }
+  const svgPath = siblingSvgPath(sourcePath);
+  if (svgPath === sourcePath) throw failExport("not-svg", sourcePath, "无法把源文件路径换成 .svg");
+  const hash = sourceHash(fs.readFileSync(sourcePath));
+  if (fs.existsSync(svgPath)) {
+    const current = fs.readFileSync(svgPath, "utf8");
+    if (svgIsCurrent(current, hash)) return svgPath;
+    fs.rmSync(svgPath, { force: true });
+  }
+  const render = options.render ?? ((input, output) => renderWithBinary(input, output, options));
+  try {
+    render(sourcePath, svgPath);
+    if (!fs.existsSync(svgPath) || !fs.statSync(svgPath).isFile()) throw failExport("no-output", svgPath);
+    const raw = fs.readFileSync(svgPath, "utf8");
+    assertFlatSvg(raw, svgPath);
+    fs.writeFileSync(svgPath, stampSvg(raw, hash));
+  } catch (error) {
+    fs.rmSync(svgPath, { force: true });
+    if (error instanceof ExcalidrawExportError) throw error;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw failExport("export-failed", sourcePath, reason);
+  }
+  return svgPath;
+}

package/ui/core/transform.mjs

@@ -86,9 +86,17 @@ const absolute = (src, siteUrl) => (src && siteUrl && src.startsWith("/") ? `${s
 const escapeHtml = (value) =>
   String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 
+/** Text a reader can select inside an inlined Excalidraw SVG; path data and fonts stay out of search. */
+function excalidrawVisibleText(svg) {
+  const parts = [];
+  for (const match of svg.matchAll(/<(?:text|title)\b[^>]*>([^<]*)<\/(?:text|title)>/giu)) parts.push(match[1]);
+  return parts.join(" ");
+}
+
 /** Readable text for search and word count: captions and snapshot text, never intent. */
 export function contentToSearchText(content) {
-  return replaceFences(stripCardMarkers(content), (fence) => {
+  const withoutDiagramMarkup = String(content ?? "").replace(/<svg\b[^>]*class="[^"]*\bexcalidraw\b[^"]*"[\s\S]*?<\/svg>/giu, (svg) => ` ${excalidrawVisibleText(svg)} `);
+  return replaceFences(stripCardMarkers(withoutDiagramMarkup), (fence) => {
     if (fence.lang === "ui") {
       const payload = readPayload(fence.body);
       if (!payload) return " ";

package/ui/garden/excalidraw-inline.mjs

@@ -0,0 +1,175 @@
+/**
+ * Turn an exported Excalidraw SVG into article HTML.
+ *
+ * The Markdown image stays the author's syntax until content sync. This walks
+ * the Markdown AST, swaps each `.excalidraw` image for the sanitized SVG, and
+ * leaves every other byte of the post alone. rehype-raw then parses that SVG
+ * into the article tree, so the text is part of the page rather than an
+ * `<img src>`.
+ */
+import crypto from "node:crypto";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { fromHtml } from "hast-util-from-html";
+import { toHtml } from "hast-util-to-html";
+import { visit } from "unist-util-visit";
+import { figureLayout } from "./enhance.mjs";
+import { mapOutsideCode } from "./markdown-links.mjs";
+
+/** Same rule as scripts/excalidraw.mjs: a source file, not an `.excalidraw.svg`. */
+function isExcalidrawPath(value) {
+  const clean = String(value ?? "").split(/[?#]/u, 1)[0];
+  return /\.excalidraw$/iu.test(clean);
+}
+
+const DROP_TAGS = new Set([
+  "script",
+  "noscript",
+  "iframe",
+  "object",
+  "embed",
+  "foreignobject",
+  "audio",
+  "video",
+  "canvas",
+  "link",
+  "meta",
+  "base",
+  "form",
+]);
+
+const escapeHtml = (value) =>
+  String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+
+function meaningfulChildren(node) {
+  return (node?.children ?? []).filter((child) => !(child.type === "text" && !String(child.value).trim()));
+}
+
+/** Same caption rule as article figures: title, otherwise alt, unless the alt is a placeholder. */
+function imageCaption(image) {
+  const title = String(image.title ?? "").trim();
+  const alt = String(image.alt ?? "").trim();
+  if (title) return title;
+  if (alt && !/^image|^截图|^img/iu.test(alt)) return alt;
+  return "";
+}
+
+function unsafeUrl(value) {
+  const url = String(value ?? "").trim().replace(/[\u0000-\u001f\s]+/gu, "");
+  if (!url || url.startsWith("#") || url.startsWith("/")) return false;
+  if (/^javascript:/iu.test(url)) return true;
+  if (/^https?:/iu.test(url)) return false;
+  if (/^data:image\/(?:png|gif|jpe?g|webp|svg\+xml);/iu.test(url)) return false;
+  if (/^data:font\//iu.test(url)) return false;
+  if (/^data:/iu.test(url)) return true;
+  return false;
+}
+
+function sanitizeNode(node) {
+  if (!node || node.type === "text" || node.type === "comment") return node;
+  if (node.type !== "element") return null;
+  if (DROP_TAGS.has(String(node.tagName).toLowerCase())) return null;
+  const properties = { ...(node.properties ?? {}) };
+  for (const key of Object.keys(properties)) {
+    const value = properties[key];
+    if (/^on/iu.test(key)) {
+      delete properties[key];
+      continue;
+    }
+    if (typeof value === "string" && /^(?:href|src|xlinkHref)$/iu.test(key) && unsafeUrl(value)) {
+      delete properties[key];
+      continue;
+    }
+    if (key === "style" && typeof value === "string" && /javascript:/iu.test(value)) delete properties[key];
+  }
+  node.properties = properties;
+  node.children = (node.children ?? []).map(sanitizeNode).filter(Boolean);
+  return node;
+}
+
+/**
+ * Sanitized SVG markup for the page. Alt or title becomes `<title>` and
+ * `aria-labelledby`. Scene `<text>` nodes stay.
+ * @param {string} svgText
+ * @param {{ alt?: string, title?: string }} [labels]
+ */
+export function inlineSvgDocument(svgText, { alt = "", title = "" } = {}) {
+  const stripped = String(svgText).replace(/<!--\s*garden-excalidraw-source:[^>]*-->/gu, "");
+  const root = fromHtml(stripped, { fragment: true });
+  const svg = root.children.find((node) => node.type === "element" && node.tagName === "svg");
+  if (!svg) throw new Error("导出结果不是 SVG");
+  sanitizeNode(svg);
+  const label = String(title || alt || "").trim();
+  if (label) {
+    const id = `garden-excalidraw-${crypto.createHash("sha256").update(`${label}\0${stripped}`).digest("hex").slice(0, 10)}`;
+    svg.properties.ariaLabelledby = id;
+    svg.children.unshift({
+      type: "element",
+      tagName: "title",
+      properties: { id },
+      children: [{ type: "text", value: label }],
+    });
+  }
+  const classes = Array.isArray(svg.properties.className)
+    ? svg.properties.className
+    : svg.properties.className
+      ? [svg.properties.className]
+      : [];
+  if (!classes.includes("excalidraw")) classes.push("excalidraw");
+  svg.properties.className = classes;
+  const width = Number(svg.properties.width) || 0;
+  const height = Number(svg.properties.height) || 0;
+  if (width > 0) svg.properties.dataNw = String(width);
+  if (width > 0) svg.properties.dataAw = String(width);
+  return { html: toHtml(svg), width, height };
+}
+
+function figureHtml(svgHtml, caption, width) {
+  const side = figureLayout({ naturalWidth: width }).side;
+  const classes = side > 0 ? "fig fig-wide" : "fig";
+  const style = side > 0 ? ` style="--wl:${side}px;--wr:${side}px"` : "";
+  const cap = caption ? `<figcaption>${escapeHtml(caption)}</figcaption>` : "";
+  return `<figure class="${classes}"${style}><div class="fig-card">${svgHtml}</div>${cap}</figure>`;
+}
+
+/**
+ * Replace `.excalidraw` Markdown images with inline SVG HTML.
+ * `readSvg(url)` returns the exported SVG text or throws.
+ * @param {string} markdown
+ * @param {(url: string) => string} readSvg
+ */
+export function embedExcalidrawImages(markdown, readSvg) {
+  const source = String(markdown ?? "");
+  const tree = fromMarkdown(source);
+  const edits = [];
+  visit(tree, "image", (node, _index, parent) => {
+    const url = String(node.url ?? "");
+    if (!isExcalidrawPath(url)) return;
+    const start = node.position?.start?.offset;
+    const end = node.position?.end?.offset;
+    if (start == null || end == null) return;
+    const { html, width } = inlineSvgDocument(readSvg(url), { alt: node.alt, title: node.title });
+    const alone = parent?.type === "paragraph" && meaningfulChildren(parent).length === 1 && meaningfulChildren(parent)[0] === node;
+    const caption = imageCaption(node);
+    edits.push(alone && parent.position?.start?.offset != null && parent.position?.end?.offset != null
+      ? { start: parent.position.start.offset, end: parent.position.end.offset, replacement: figureHtml(html, caption, width) }
+      : { start, end, replacement: html });
+  });
+  edits.sort((left, right) => right.start - left.start);
+  let output = source;
+  for (const edit of edits) output = `${output.slice(0, edit.start)}${edit.replacement}${output.slice(edit.end)}`;
+  return output;
+}
+
+/** Raw `<img src="….excalidraw">` outside code becomes the same inline SVG. */
+export function embedExcalidrawImgTags(markdown, readSvg) {
+  return mapOutsideCode(markdown, (text) => text.replace(/<img\b[^>]*>/giu, (tag) => {
+    const src = /\bsrc\s*=\s*["']([^"']+)["']/iu.exec(tag)?.[1];
+    if (!src || !isExcalidrawPath(src)) return tag;
+    const alt = /\balt\s*=\s*["']([^"']*)["']/iu.exec(tag)?.[1] ?? "";
+    return inlineSvgDocument(readSvg(src), { alt }).html;
+  }));
+}