hd-garden 0.10.2 → 0.10.4

package/docs/handbook/en/ai-writing.md

@@ -1,7 +1,7 @@
 ---
 title: Writing with AI
 navTitle: Writing with AI
-description: Describe components in one sentence for an Agent to compile, and validate staged files with the same CLI in the pre-commit hook.
+description: Insert and preview ideas with the editor plugins, let an Agent compile them, and validate staged files with the same CLI.
 section: getting-started
 order: 2
 ---
@@ -82,15 +82,35 @@ Compared with the previous version: split the title into two lines with " | " in
 
 Following the `garden-ui` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
 
-## 6. Templates and Snippets Without an Agent
+## 6. Insert, Preview, and Compile from the Editor
+
+The VS Code, Cursor, and Typora Intelligent UI plugins put the flow above in the editor. They ship inside `hd-garden`. `npx hd-garden init` copies them to `.garden/editors/` and asks whether to install them when the terminal is interactive. The first `npx garden sync` asks again if that prompt has not happened yet. A non-interactive shell, `CI=1`, or `GARDEN_SKIP_EDITORS=1` prints the hint and does not block. Install later with:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+A component then takes four steps:
+
+1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-ui` skill which component to compile and which facts to include.
+2. **Preview.** Open the Markdown preview, or in Typora move the cursor out of the fence. An `intent` block shows as an idea card. After the skill writes a `ui` block, the preview matches the blog. VS Code / Cursor also report errors in Problems and in the CodeLens above the block.
+3. **Open the catalog.** Use the catalog command, or run `npx garden ui catalog` and open `.garden/ui-catalog.html`. Starting from a recipe inserts it at the cursor when you already know which component you want.
+4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-ui` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
+
+**Typora prerequisite.** Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. `npx garden editors install --typora` copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework; reinstall the framework, then enable the plugin again. If `code` or `cursor` is not on `PATH`, use Install from VSIX in the Extensions view and select the file under `.garden/editors/vscode/`. Install details are in [Checks & Shortcuts](/garden/en/workflow).
+
+## 7. Templates and Snippets Without an Agent
 
 When writing components by hand without AI, you can use the templates and snippets shipped in the package:
 
 - Every draft created by `make new` includes an HTML comment at the bottom with copy-ready examples for idea fences and all 12 components; delete the comment whenever you are done.
 - `templates/garden-blocks.md` lists `when` / `whenNot` guidance and copyable templates for every block; macOS, Typora, and Alfred users can import `templates/garden-snippets.plist` to expand `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gfigure`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`.
-- The engine repository also ships editor integrations under `editors/vscode`, `editors/typora`, and `editors/obsidian`, and `npx garden ui catalog` generates an offline component catalog at `.garden/ui-catalog.html`.
+- Editor plugin usage is in the previous section. `npx garden ui catalog` writes an offline component catalog at `.garden/ui-catalog.html`.
 
-## 7. Optional Standalone Admin
+## 8. Optional Standalone Admin
 
 The Garden engine includes an optional `/admin` console (under `app/admin` and `worker/`) that can be deployed separately with `npm run admin:local`, `npm run admin:cloudflare`, or Docker. Once configured via environment variables, it provides:
 

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/index.md

@@ -187,6 +187,7 @@ make dev
 Run `make update` when a post is ready; it runs the full check and build before committing and pushing. Read the chapters for details:
 
 - **[Quick Start](/garden/en/start)**: Directory layout, creating posts with `make new`, previewing drafts, and daily commands.
+- **[Writing with AI](/garden/en/ai-writing)** and **[Checks & Shortcuts](/garden/en/workflow)**: Insert an idea, preview the component, and open the catalog in VS Code, Cursor, or Typora, and install the plugins with `npx garden editors install`.
 - **[Site & Column Config](/garden/en/config)**: Every field in `site.config.yaml`, custom SVG icons, and ordering series in `content/columns.yaml`.
 - **[Deploy to GitHub Pages](/garden/en/deploy)**: A single GitHub Actions workflow that supports both one public repository and a private source repo paired with a public Pages repo.
 - **[Writing Posts & Thoughts](/garden/en/writing)** and **[How the Reading Layout Works](/garden/en/design)**: Front Matter fields, three-tier adaptive widths, and color tokens. Link cards, source chips, and local images are on [Components Overview](/garden/en/components).

package/docs/handbook/en/start.md

@@ -90,3 +90,16 @@ To upgrade the engine, edit `package.json` in your site root, update the `"hd-ga
 npm install
 make check
 ```
+
+## 5. Editor Plugins
+
+To write an interactive component, insert an idea in VS Code, Cursor, or Typora, preview it, open the catalog, and let the `garden-ui` skill compile it. The plugins ship inside `hd-garden`. You do not compile them yourself.
+
+`npx hd-garden init` copies the files to `.garden/editors/`. An interactive terminal asks whether to install VS Code / Cursor and whether to install Typora. The first `npx garden sync` asks again if that prompt has not happened yet. With no TTY, `CI=1`, or `GARDEN_SKIP_EDITORS=1`, Garden only prints the hint. Install later with:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+```
+
+Typora needs typora-community-plugin installed first; then enable the plugin under Settings, Installed plugins. If `code` or `cursor` is not available, use Install from VSIX and select the file under `.garden/editors/vscode/`. Insert, preview, catalog, and compile steps are in [Writing with AI](/garden/en/ai-writing) and [Checks & Shortcuts](/garden/en/workflow).

package/docs/handbook/en/workflow.md

@@ -1,7 +1,7 @@
 ---
 title: Checks & Shortcuts
 navTitle: Checks & Shortcuts
-description: Validate posts and diagnostic codes with npx garden check, install the Git pre-commit hook, and use editor snippets and Agent skills.
+description: Validate posts with npx garden check, install the VS Code and Typora plugins, and set up the Git pre-commit hook and Agent skills.
 section: workflow
 order: 40
 ---
@@ -80,3 +80,41 @@ Garden provides three ways to insert or generate components quickly:
    - `garden-ui`: Compiles natural-language `garden` idea fences into concrete component blocks.
    - `garden-interactive-chart`: Authors `interactive`, `chart`, `figure`, and `html` components from article data.
    - `garden-post-review`: Reviews an entire post against layout and component rules.
+
+## 5. VS Code, Cursor, and Typora Plugins
+
+The Intelligent UI plugins are the editor entry point for interactive components: insert a one-sentence idea, preview it, open the catalog, then hand compilation to the `garden-ui` skill. They ship inside `hd-garden`. A site does not compile `editors/vscode` or `editors/typora` from source.
+
+### Install
+
+`npx hd-garden init` copies the files to `.garden/editors/` (a VSIX for VS Code / Cursor, and the Typora plugin). An interactive terminal asks whether to install VS Code / Cursor, then whether to install Typora. The first `npx garden sync` or `npx garden dev` asks again when that prompt has not happened yet. `y` installs; Enter skips.
+
+With no TTY, when `CI` is `1`, or when `GARDEN_SKIP_EDITORS` is set, Garden does not wait for input and only prints how to install later. `GARDEN_SKIP_EDITORS` skips that automatic prompt. The commands below still install, and they are safe to run again:
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+`garden help` lists `editors install`.
+
+**VS Code / Cursor.** When `code` or `cursor` is on `PATH`, install adds the VSIX to that editor. If both commands exist, it installs into both. Without a CLI, open the Extensions view, choose the `...` menu, then Install from VSIX, and select the file under `.garden/editors/vscode/`.
+
+**Typora.** Typora has no official plugin API. Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. The install command checks the usual locations. If the framework is missing, it still copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/` and prints that prerequisite. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Open Typora and enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework inside the app. Reinstall typora-community-plugin, then enable this plugin again. The fences stay in the Markdown.
+
+The Obsidian plugin is not installed by this command.
+
+### Use the plugins while writing
+
+1. **Insert an idea.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden` (the next list has a small preview image on each row), or use the insert command to open the component list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The insertion is a plain `garden` fence: a short brief naming the component and the facts to mention, which the `garden-ui` skill compiles later.
+2. **Preview.** Open the Markdown preview. In Typora, move the cursor out of the fence. A `ui` block renders the same component as the blog. An `intent` block renders as an idea card. Clicks on sliders and buttons stay in the preview.
+3. **Open the catalog.** In VS Code / Cursor, the catalog command inserts a recipe at the cursor. The terminal builds the same page:
+
+   ```bash
+   npx garden ui catalog
+   ```
+
+   That writes `.garden/ui-catalog.html`.
+4. **Compile with the skill.** Copy compile prompt. On an English site (`locale: en_US`) the clipboard text is `Compile this post:` plus the post path. Paste it to an Agent that has the `garden-ui` skill. The skill runs `npx garden ui scan`, reads `npx garden ui prompt`, and replaces only that fence with `npx garden ui apply`. The plugin does not call a model. Check the result with `npx garden ui check` or the pre-commit hook.

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/index.md

@@ -182,6 +182,7 @@ make dev
 写完运行 `make update`，检查通过后会提交并推送。细节见各章：
 
 - **[快速开始](/garden/start)**：目录结构、`make new` 新建长文、草稿预览与日常命令。
+- **[用 AI 写作](/garden/ai-writing)** 与 **[语法检查与快捷输入](/garden/workflow)**：在 VS Code、Cursor、Typora 里插入想法、预览组件、打开清单，并用 `npx garden editors install` 安装插件。
 - **[站点与专栏配置](/garden/config)**：`site.config.yaml` 各字段含义、自定义 SVG 图标与 `content/columns.yaml` 专栏编排。
 - **[发布到 GitHub Pages](/garden/deploy)**：单个公开仓库或「私有源码仓库 + 公开页面仓库」的完整 Actions 工作流。
 - **[写文章与随想](/garden/writing)** 与 **[阅读排版是怎么工作的](/garden/design)**：Front Matter 字段、三级自适应宽度与色彩变量。链接卡片、来源胶囊和本地图片见 [组件总览](/garden/components)。

package/docs/handbook/start.md

@@ -90,3 +90,16 @@ CONTENT_INCLUDE_DRAFTS=1 make dev
 npm install
 make check
 ```
+
+## 5. 编辑器插件
+
+写交互组件时，可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，不用自己编译。
+
+`npx hd-garden init` 会把产物放到 `.garden/editors/`。终端可交互时分别询问是否安装 VS Code / Cursor 和 Typora。第一次 `npx garden sync` 如果还没问过，会再问一次。没有 TTY、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 时只打印提示。之后运行：
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+```
+
+Typora 需要先安装 typora-community-plugin，再在「设置 → 已安装插件」里勾选。没有 `code` 或 `cursor` 命令时，用 Install from VSIX 选择 `.garden/editors/vscode/` 里的文件。插入、预览、清单和编译的步骤见 [用 AI 写作](/garden/ai-writing) 与 [语法检查与快捷输入](/garden/workflow)。

package/docs/handbook/workflow.md

@@ -1,7 +1,7 @@
 ---
 title: 语法检查与快捷输入
 navTitle: 语法检查与快捷输入
-description: 使用 npx garden check 检查文章诊断码，配置 Git 提交前检查钩子、编辑器代码片段与 Agent 技能。
+description: 使用 npx garden check 检查文章诊断码，安装 VS Code 与 Typora 插件，配置 Git 提交前检查钩子与 Agent 技能。
 section: workflow
 order: 40
 ---
@@ -80,3 +80,41 @@ Garden 通过以下三种方式提供组件模板与智能辅助：
    - `garden-ui`：把文章里的 `garden` 想法描述编译成具体的组件围栏。
    - `garden-interactive-chart`：根据文章数据编写 `interactive`、`chart`、`figure` 与 `html` 组件。
    - `garden-post-review`：按排版与组件规范审阅整篇文章。
+
+## 5. VS Code、Cursor 与 Typora 插件
+
+Intelligent UI 插件是写交互组件的编辑器入口：插入一句想法、在编辑器里预览、打开组件清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
+
+### 安装
+
+`npx hd-garden init` 把产物复制到 `.garden/editors/`（VS Code / Cursor 的 VSIX，以及 Typora 插件）。终端可交互时会分别询问要不要装进 VS Code / Cursor、要不要装进 Typora。第一次 `npx garden sync` 或 `npx garden dev` 如果还没问过，会再问一次。`y` 安装，直接回车跳过。
+
+没有 TTY、环境变量 `CI` 为 `1`，或设置了 `GARDEN_SKIP_EDITORS` 时，不会等待输入，只提示手动安装。`GARDEN_SKIP_EDITORS` 只跳过这次自动询问；下面的命令照常安装，并且可以重复执行：
+
+```bash
+npx garden editors install
+npx garden editors install --yes
+npx garden editors install --vscode
+npx garden editors install --typora
+```
+
+`garden help` 里也能看到 `editors install`。
+
+**VS Code / Cursor。** 本机有 `code` 或 `cursor` 时，安装会把 VSIX 装进那个编辑器。两个命令都在时各装一次。没有命令行时，打开扩展视图，点右上角「…」，选择 Install from VSIX，文件在 `.garden/editors/vscode/`。
+
+**Typora。** Typora 没有官方插件接口，要先安装 [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md)。安装命令会检查常见位置；没找到时仍把插件复制到 `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`。macOS 还会复制到 `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`。然后打开 Typora，在「设置 → 已安装插件」里勾选 Garden Intelligent UI。升级 Typora 会覆盖社区框架改过的程序文件，需要重新安装 typora-community-plugin，再勾选本插件。围栏原文还在稿件里。
+
+Obsidian 插件这一轮不随包安装。
+
+### 在编辑器里怎么用
+
+1. **插入想法。** VS Code / Cursor：macOS 用 `Cmd+Alt+I`，Windows / Linux 用 `Ctrl+Alt+I`，或命令「插入 Garden 块」。Typora：输入 `/` 后选 `/garden`（下一层列表每一项有一张小预览图），或命令「插入 Garden 块」直接打开组件列表（Windows / Linux 默认 `Ctrl+Alt+I`，macOS 请到「设置 → 快捷键」里自己录，因为 Option 会改写按键）。插入的是不带组件名的 `garden` 围栏，正文说明要写成哪种组件、写上哪些事实，交给 `garden-ui` skill 编译。
+2. **预览。** 打开 Markdown 预览（Typora 里光标离开围栏即可）。`ui` 块画成和博客一样的组件，`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
+3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」，点「用它开始」把配方插进当前稿件。终端里的同一份清单：
+
+   ```bash
+   npx garden ui catalog
+   ```
+
+   生成 `.garden/ui-catalog.html`。
+4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇：<相对路径>`，在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-ui` skill 的 Agent。它会运行 `npx garden ui scan`，阅读 `npx garden ui prompt`，再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。

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 图表