hd-garden 0.8.0 → 0.8.2

package/scripts/link-assets.mjs

@@ -19,6 +19,7 @@ import matter from "gray-matter";
 import { fetchFavicon, fetchImage, fetchPageMeta, isPublicUrl, linkHost } from "./link-meta-core.mjs";
 import { parse as parseYaml } from "yaml";
 import { markdownLinks } from "../ui/garden/markdown-links.mjs";
+import { gardenSourceUrls } from "../ui/garden/source-icon.mjs";
 import { configuredSiteAddress, sameSiteMatcher } from "../ui/garden/same-site.mjs";
 
 export const CACHE_FILE = "link-assets.json";
@@ -76,6 +77,12 @@ export function collectSiteLinks(siteRoot, env = process.env) {
       const host = linkHost(url);
       if (host && !hosts.has(host)) hosts.set(host, url);
     }
+    // Card sources get the same favicon as links to that site.
+    for (const url of gardenSourceUrls(content)) {
+      if (!isPublicUrl(url) || sameSite(url)) continue;
+      const host = linkHost(url);
+      if (host && !hosts.has(host)) hosts.set(host, url);
+    }
   }
   return { hosts, cards, urls };
 }

package/scripts/new-post.mjs

@@ -3,12 +3,14 @@ import { lstat, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { formatAuthorDate } from "./site-date.mjs";
 import { cheatSheet } from "../ui/garden/catalog.mjs";
+import { siteCliLang } from "../ui/core/cli-locale.mjs";
 
 const root = path.resolve(process.env.GARDEN_SITE || process.cwd());
 const option = (name) => (process.env[`GARDEN_NEW_${name}`] ?? "").trim();
 
 async function main() {
-  const title = option("TITLE") || "新文章";
+  const lang = siteCliLang(root);
+  const title = option("TITLE") || (lang === "en" ? "New Post" : "新文章");
   const date = formatAuthorDate();
   const titleSlug = title.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "");
   const slug = option("SLUG") || titleSlug || `post-${date.slice(0, 10)}-${randomUUID().slice(0, 8)}`;
@@ -41,16 +43,16 @@ async function main() {
     "---",
     `title: ${JSON.stringify(title)}`,
     `date: ${date}`,
-    `description: ${JSON.stringify("请填写一句话摘要。")}`,
+    `description: ${JSON.stringify(lang === "en" ? "Write a one-sentence summary." : "请填写一句话摘要。")}`,
     "tags: []",
     "draft: true",
     "---",
     "",
-    "## 起因",
+    lang === "en" ? "## Context" : "## 起因",
     "",
-    "从这里开始写正文。",
+    lang === "en" ? "Start writing here." : "从这里开始写正文。",
     "",
-    cheatSheet(),
+    cheatSheet(lang),
     "",
   ].join("\n");
   try {
@@ -62,10 +64,17 @@ async function main() {
     throw error;
   }
 
-  console.log(`已创建草稿：${path.relative(root, destination)}`);
-  console.log(`文章路径：/blog/${[...segments, slug].join("/")}/`);
-  console.log("预览：CONTENT_INCLUDE_DRAFTS=1 make dev");
-  console.log("发布前请完善摘要、标签与正文，并将 draft 改为 false，再运行 make update。");
+  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("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("发布前请完善摘要、标签与正文，并将 draft 改为 false，再运行 make update。");
+  }
 }
 
 main().catch((error) => {

package/scripts/prepare-pages-output.mjs

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { langOf, siteCliLang } from "../ui/core/cli-locale.mjs";
 import { STATIC_PLACEHOLDER } from "../ui/garden/static-params.mjs";
 
 const forbiddenDirectoryNames = new Set([
@@ -30,8 +31,12 @@ const isPublishedFile = (relativePath) =>
   publishedExtensions[relativePath.split("/", 1)[0]]?.has(path.extname(relativePath)) === true;
 const deploymentVersionPlaceholder = "00000000-0000-4000-8000-000000000000";
 
+const cliLang = process.env.GARDEN_LOCALE ? langOf(process.env.GARDEN_LOCALE) : siteCliLang(process.env.GARDEN_SITE ?? process.cwd());
+/** Chinese or English CLI text, by the site's locale. */
+const msg = (zh, en) => (cliLang === "en" ? en : zh);
+
 function fail(message) {
-  throw new Error(`Pages 产物无效：${message}`);
+  throw new Error(msg(`Pages 产物无效：${message}`, `Invalid Pages output: ${message}`));
 }
 
 async function assertDirectory(directory, label) {
@@ -39,9 +44,9 @@ async function assertDirectory(directory, label) {
   try {
     stat = await fs.stat(directory);
   } catch {
-    fail(`${label}不存在：${directory}`);
+    fail(msg(`${label}不存在：${directory}`, `${label} does not exist: ${directory}`));
   }
-  if (!stat.isDirectory()) fail(`${label}不是目录：${directory}`);
+  if (!stat.isDirectory()) fail(msg(`${label}不是目录：${directory}`, `${label} is not a directory: ${directory}`));
 }
 
 async function inspectTree(root, directory = root) {
@@ -51,20 +56,20 @@ async function inspectTree(root, directory = root) {
     const relativePath = path.relative(root, absolutePath).split(path.sep).join("/");
     const stat = await fs.lstat(absolutePath);
 
-    if (stat.isSymbolicLink()) fail(`不允许软链接：${relativePath}`);
+    if (stat.isSymbolicLink()) fail(msg(`不允许软链接：${relativePath}`, `Symlinks are not allowed: ${relativePath}`));
     if (forbiddenDirectoryNames.has(entry.name)) {
-      fail(`不允许源码目录：${relativePath}`);
+      fail(msg(`不允许源码目录：${relativePath}`, `Source directories are not allowed: ${relativePath}`));
     }
-    if (entry.name.startsWith(".env")) fail(`不允许环境文件：${relativePath}`);
-    if (entry.name.startsWith(STATIC_PLACEHOLDER)) fail(`空动态路由的占位页没有删掉：${relativePath}`);
+    if (entry.name.startsWith(".env")) fail(msg(`不允许环境文件：${relativePath}`, `Environment files are not allowed: ${relativePath}`));
+    if (entry.name.startsWith(STATIC_PLACEHOLDER)) fail(msg(`空动态路由的占位页没有删掉：${relativePath}`, `Placeholder page for an empty dynamic route was not removed: ${relativePath}`));
     if (/^package(?:-lock)?\.json$/u.test(entry.name)) {
-      fail(`不允许依赖清单：${relativePath}`);
+      fail(msg(`不允许依赖清单：${relativePath}`, `Dependency manifests are not allowed: ${relativePath}`));
     }
     if (forbiddenFileNames.has(entry.name)) {
-      fail(`不允许源码配置：${relativePath}`);
+      fail(msg(`不允许源码配置：${relativePath}`, `Source config files are not allowed: ${relativePath}`));
     }
     if (entry.isFile() && forbiddenExtensions.has(path.extname(entry.name)) && !isPublishedFile(relativePath)) {
-      fail(`不允许源码或 Source Map：${relativePath}`);
+      fail(msg(`不允许源码或 Source Map：${relativePath}`, `Source files or source maps are not allowed: ${relativePath}`));
     }
     if (entry.isDirectory()) await inspectTree(root, absolutePath);
   }
@@ -163,25 +168,25 @@ async function stabilizeDeploymentVersion(root) {
 
 export async function validateStaticOutput(sourceDirectory) {
   const source = path.resolve(sourceDirectory);
-  await assertDirectory(source, "静态产物目录");
+  await assertDirectory(source, msg("静态产物目录", "Static output directory"));
   await fs.access(path.join(source, "index.html")).catch(() => {
-    fail(`缺少入口文件：${path.join(source, "index.html")}`);
+    fail(msg(`缺少入口文件：${path.join(source, "index.html")}`, `Missing entry file: ${path.join(source, "index.html")}`));
   });
   await inspectTree(source);
   return source;
 }
 
-export async function preparePagesOutput(sourceDirectory, destinationDirectory) {
+export async function preparePagesOutput(sourceDirectory, destinationDirectory, options = {}) {
   const source = await validateStaticOutput(sourceDirectory);
   const destination = path.resolve(destinationDirectory);
-  await assertDirectory(destination, "Pages 仓库目录");
+  await assertDirectory(destination, msg("Pages 仓库目录", "Pages repository directory"));
   await fs.access(path.join(destination, ".git")).catch(() => {
-    fail(`目标不是 Git 仓库：${destination}`);
+    fail(msg(`目标不是 Git 仓库：${destination}`, `Destination is not a Git repository: ${destination}`));
   });
 
   const relativeFromDestination = path.relative(destination, source);
   if (!relativeFromDestination.startsWith("..") && !path.isAbsolute(relativeFromDestination)) {
-    fail("静态产物目录不能位于目标仓库内部");
+    fail(msg("静态产物目录不能位于目标仓库内部", "The static output directory cannot be inside the destination repository"));
   }
 
   for (const entry of await fs.readdir(destination, { withFileTypes: true })) {
@@ -191,9 +196,16 @@ export async function preparePagesOutput(sourceDirectory, destinationDirectory)
 
   await fs.cp(source, destination, { recursive: true, force: true });
   await fs.writeFile(path.join(destination, ".nojekyll"), "");
+  let isEn = options.lang === "en" || /^en/iu.test(String(process.env.GARDEN_LOCALE ?? ""));
+  if (!isEn && options.lang !== "zh") {
+    const indexHtml = await fs.readFile(path.join(source, "index.html"), "utf8").catch(() => "");
+    if (/<html\b[^>]*\slang="en(?:-US)?"/iu.test(indexHtml)) isEn = true;
+  }
   await fs.writeFile(
     path.join(destination, "README.md"),
-    "# Garden 静态站点\n\n此仓库只保存 Garden 自动生成的公开静态文件，请勿手工编辑。\n",
+    isEn
+      ? "# Garden Static Site\n\nThis repository holds public static files generated automatically by Garden. Do not edit by hand.\n"
+      : "# Garden 静态站点\n\n此仓库只保存 Garden 自动生成的公开静态文件，请勿手工编辑。\n",
   );
   await stabilizeDeploymentVersion(destination);
 }
@@ -204,7 +216,7 @@ const invokedDirectly = process.argv[1] &&
 if (invokedDirectly) {
   const [, , sourceDirectory, destinationDirectory] = process.argv;
   if (!sourceDirectory || process.argv.length > 4) {
-    throw new Error("用法：node scripts/prepare-pages-output.mjs <静态产物目录> [Pages 仓库目录]");
+    throw new Error(msg("用法：node scripts/prepare-pages-output.mjs <静态产物目录> [Pages 仓库目录]", "Usage: node scripts/prepare-pages-output.mjs <static output directory> [Pages repository directory]"));
   }
   if (destinationDirectory) {
     await preparePagesOutput(sourceDirectory, destinationDirectory);

package/scripts/redirects.mjs

@@ -35,20 +35,26 @@ export function redirectFile(from) {
   return /\.html?$/iu.test(clean) ? clean : path.posix.join(clean.replace(/\/+$/u, ""), "index.html");
 }
 
-export function redirectPage({ href, canonical, icon = "" }) {
+export function redirectPage({ href, canonical, icon = "", lang = "zh" }) {
   // The site's own icon, so the browser does not go looking for /favicon.ico.
   const iconLink = icon ? `\n<link rel="icon" href="${escapeHtml(icon)}"${/\.svg(?:[?#]|$)/iu.test(icon) ? ' type="image/svg+xml"' : ""}>` : "";
+  const isEn = lang === "en";
+  const htmlLang = isEn ? "en" : "zh-CN";
+  const title = isEn ? "Page moved" : "页面已移动";
+  const bodyText = isEn
+    ? `<p>This page has moved to <a href="${escapeHtml(href)}">${escapeHtml(canonical)}</a>.</p>`
+    : `<p>页面已移到 <a href="${escapeHtml(href)}">${escapeHtml(canonical)}</a>。</p>`;
   return `<!doctype html>
-<html lang="zh-CN">
+<html lang="${htmlLang}">
 <head>
 <meta charset="utf-8">
-<title>页面已移动</title>
+<title>${title}</title>
 <link rel="canonical" href="${escapeHtml(canonical)}">${iconLink}
 <meta http-equiv="refresh" content="0; url=${escapeHtml(href)}">
 <script>location.replace(${JSON.stringify(href).replace(/</gu, "\\u003c")}${href.includes("#") ? "" : " + location.hash"})</script>
 </head>
 <body>
-<p>页面已移到 <a href="${escapeHtml(href)}">${escapeHtml(canonical)}</a>。</p>
+${bodyText}
 </body>
 </html>
 `;
@@ -67,6 +73,7 @@ export function redirectPage({ href, canonical, icon = "" }) {
  */
 export function generateRedirects({ outDir, config = {}, env = {}, basePath = "", log = () => {}, extra = [], icon = "" }) {
   const base = String(basePath ?? "").replace(/\/+$/u, "");
+  const lang = /^en/iu.test(String(config?.locale ?? "")) ? "en" : "zh";
   let origin = "";
   try {
     const address = configuredSiteAddress(config, env);
@@ -118,7 +125,7 @@ export function generateRedirects({ outDir, config = {}, env = {}, basePath = ""
     const href = external ? to : withTrailingSlash(`${base}${to}`);
     const canonical = external || !origin ? href : `${origin}${href}`;
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, redirectPage({ href, canonical, icon }));
+    fs.writeFileSync(file, redirectPage({ href, canonical, icon, lang }));
     written.push({ from, to: href, file });
   }
   return { written, expected: pairs.length, skipped };
@@ -136,7 +143,11 @@ export function writeRedirects(options) {
  * warning (a page went missing without a reason).
  */
 export function runRedirectStep({ siteRoot, env = process.env, out = process.stdout, err = process.stderr, generate = generateRedirects }) {
-  const outDir = path.join(siteRoot, "dist", "client");
+  const baseDir = String(env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/^\/+|\/+$/gu, "");
+  // A base-path build exports pages under dist/client/<base>/, so old paths and targets live there.
+  const outDir = baseDir && fs.existsSync(path.join(siteRoot, "dist", "client", baseDir))
+    ? path.join(siteRoot, "dist", "client", baseDir)
+    : path.join(siteRoot, "dist", "client");
   try {
     const config = parseYaml(fs.readFileSync(path.join(siteRoot, "site.config.yaml"), "utf8")) ?? {};
     const columnsFile = path.join(siteRoot, "content", "columns.yaml");

package/templates/garden-blocks.md

@@ -137,3 +137,70 @@ intent: |
 src: ./post-name/spec.zip
 note: 一句话说明里面有什么
 ```
+
+## relations · 关系图
+
+三到六个关键要素，读者需要看清谁影响谁、哪些是双向的；首尾相接的循环也用它，把每一步写成一条 link。
+
+不该用：要素更多、有分支或先后顺序时，用 ```mermaid 流程图；只走一遍的步骤用 garden list。
+
+```garden relations
+items:
+  - title: 观察
+    text: 记下发生了什么
+  - title: 假设
+    text: 猜一个原因
+  - title: 实验
+    text: 只改一个变量
+  - title: 复盘
+    text: 留下能复用的结论
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 4
+    to: 2
+    style: dashed
+    label: 改写
+caption: 复盘的结论会改写下一轮的假设。
+```
+
+## list · 图标列表
+
+几条并列的行为、信号或做法，每条配一个线条图标；带标题时每条可以写几段说明。
+
+不该用：条目之间有先后顺序或要编号时，用普通有序列表。
+
+```garden list
+items:
+  - icon: search
+    text: 搜索「降噪耳机」
+  - icon: eye
+    text: 看了 5 个商品详情
+```
+
+## choice · 选择卡
+
+给读者两三个具体选项让他选一个，每个选项有图标、一个醒目的数字和一句说明。
+
+不该用：选项会改变后面的计算结果时，写成想法，编译成 interactive。
+
+```garden choice
+title: 你更倾向哪一种？
+items:
+  - icon: shield
+    value: ¥2,950
+    text: 原装，价格略高
+    label: 更看重可靠
+  - icon: wallet
+    value: ¥2,450
+    text: 换过电池，价格更低
+    label: 更看重价格
+none:
+  label: 都不合适
+```

package/templates/garden-snippets.plist

@@ -126,5 +126,66 @@ note: 一句话说明里面有什么
     <key>shortcut</key>
     <string>;gfile</string>
   </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden relations
+items:
+  - title: 观察
+    text: 记下发生了什么
+  - title: 假设
+    text: 猜一个原因
+  - title: 实验
+    text: 只改一个变量
+  - title: 复盘
+    text: 留下能复用的结论
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 4
+    to: 2
+    style: dashed
+    label: 改写
+caption: 复盘的结论会改写下一轮的假设。
+```</string>
+    <key>shortcut</key>
+    <string>;grel</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden list
+items:
+  - icon: search
+    text: 搜索「降噪耳机」
+  - icon: eye
+    text: 看了 5 个商品详情
+```</string>
+    <key>shortcut</key>
+    <string>;glist</string>
+  </dict>
+  <dict>
+    <key>phrase</key>
+    <string>```garden choice
+title: 你更倾向哪一种？
+items:
+  - icon: shield
+    value: ¥2,950
+    text: 原装，价格略高
+    label: 更看重可靠
+  - icon: wallet
+    value: ¥2,450
+    text: 换过电池，价格更低
+    label: 更看重价格
+none:
+  label: 都不合适
+```</string>
+    <key>shortcut</key>
+    <string>;gchoice</string>
+  </dict>
 </array>
 </plist>

package/templates/site/Makefile.en

@@ -0,0 +1,45 @@
+MESSAGE ?= Update blog
+
+.DEFAULT_GOAL := help
+
+.PHONY: help new embed skill prepare dev check build update
+
+unexport TITLE SLUG DIR URL
+export GARDEN_NEW_TITLE := $(value TITLE)
+export GARDEN_NEW_SLUG := $(value SLUG)
+export GARDEN_NEW_DIR := $(value DIR)
+export GARDEN_EMBED_URL := $(value URL)
+
+help:
+	@printf "%s\n" "Common Garden commands:" "  make new                 Create a post draft with the engine" '  make new TITLE="Post title" SLUG=my-post DIR=writing' '  make embed URL="https://example.com"  Fetch external page metadata' "  make skill               Install interactive chart skills" "  make dev                 Install dependencies and preview locally" "  make build               Build the public site" "  make update              Check, commit, and push to publish"
+
+new: prepare
+	npx garden new
+
+embed:
+	@npx garden embed
+
+skill: prepare
+	npx garden skill
+
+prepare:
+	@if [ ! -d node_modules ]; then npm install; fi
+
+dev: prepare
+	npx garden dev
+
+check: prepare
+	npx garden sync && npx garden build
+
+build: prepare
+	npx garden build
+
+update:
+	@if git diff --quiet && git diff --cached --quiet && [ -z "$$(git ls-files --others --exclude-standard)" ]; then \
+		echo "No changes to publish"; \
+	else \
+		$(MAKE) check && \
+		git add -A && \
+		git commit -m "$(MESSAGE)" && \
+		git push origin HEAD; \
+	fi

package/templates/site/README.en.md

@@ -0,0 +1,15 @@
+# My Garden
+
+This repository holds only your writing and site configuration: `content/` and `site.config.yaml`. The page engine comes from [Garden](https://github.com/hedon954/garden).
+
+```bash
+npm install
+make new TITLE="Hello, World" SLUG=hello
+make dev
+```
+
+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.
+
+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`.

package/templates/site/site.config.en.yaml

@@ -0,0 +1,55 @@
+name: Garden
+tagline: Writing · Notes · Staying curious
+description: Posts, short notes, and columns.
+locale: en_US
+# Public address of the site. Full URLs pointing here inside posts render as internal links.
+# url: https://blog.example.com
+# Site icons; falls back to Garden's built-in icons when omitted.
+# brand:
+#   logo: brand/logo.svg
+#   favicon: /favicon.svg
+#   appleTouchIcon: /apple-touch-icon.png
+
+author:
+  name: Your Name
+  github: your-github-id
+  githubBio: A short bio.
+  githubPinned: []
+
+pages:
+  home:
+    title: |-
+      Notes on what I am building,
+      and questions worth thinking through.
+    subtitle: Software, reading notes, and occasional work logs.
+  blog:
+    title: Posts
+    subtitle: Finished long-form essays.
+  thoughts:
+    title: Thoughts
+    subtitle: Short notes, images, and links.
+    # How many items to show per screen; the next screen loads automatically as you scroll. Default: 10.
+    # pageSize: 10
+  columns:
+    title: Columns
+    subtitle: Series of posts meant to be read in order.
+  about:
+    title: Hi, I am Your Name.
+    subtitle: Essays and notes live here.
+    heading: About
+    paragraphs:
+      - A software engineer writing code and keeping notes on things figured out along the way.
+      - This site holds long-form posts, short thoughts, and columns.
+    quote: ""
+    focus:
+      - Software
+      - Notes
+      - Daily
+    cta:
+      href: /blog
+      label: Browse posts
+  garden:
+    title: "Write in Markdown.\nPush to update the site."
+    subtitle: ""
+
+footer: Keep writing.

package/templates/skills-en/garden-interactive-chart/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: garden-interactive-chart
+description: >-
+  Writes Garden interactive charts as self-contained HTML in a same-name
+  sidecar directory and embeds them with a short garden html fence. Use when adding
+  or editing Garden widgets, steppers, inspect grids, param benches,
+  compare views, traces, KV cache charts, or any interactive chart / same-name directory HTML.
+---
+
+# Garden interactive charts
+
+Complex interaction does not go into Markdown. Each post has a same-name directory, and every `.html` file in it is one chart that can be opened on its own. The post body only embeds a short fence.
+
+Background: [Interactive components](https://github.com/hedon954/garden/blob/main/docs/interactive-blog-components.md). Finished examples to copy: [widget-kind-examples](https://github.com/hedon954/garden/tree/main/docs/widget-kind-examples).
+
+## When to draw, when to stop
+
+Ask first: is the reader stuck because a process was frozen into a photo, a parameter is a fixed example, two dimensions were flattened, a comparison needs scrolling back and forth, or a "what if" cannot be tried? If not, write prose or Mermaid.
+
+Five primitives. Pick one before you draw:
+
+| What the reader should do | Primitive | Copy from |
+| --- | --- | --- |
+| Stop at a given beat | Stepper | [stepper.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/stepper.html), [waste.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/waste.html) |
+| Look at cells and talk about them | Inspect grid | [inspect-grid.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/inspect-grid.html) |
+| Turn a knob, watch numbers or curves | Param bench | [param-bench.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/param-bench.html) |
+| See both sides at the same moment | Compare view | [compare.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/compare.html) |
+| See the current node and current edge | Trace | [trace.html](https://github.com/hedon954/garden/blob/main/docs/widget-kind-examples/trace.html) |
+
+If it fits, change the data instead of adding a new type. Past about 9 nodes or 12 steps, split it into two charts.
+
+## File conventions
+
+When the Markdown is at `content/posts/<dir>/<slug>.md`, charts can only live in `content/posts/<dir>/<slug>/`:
+
+```text
+content/posts/windowsill-herbs.md
+content/posts/windowsill-herbs/layers.html
+```
+
+Body:
+
+````md
+```garden html
+src: ./windowsill-herbs/layers.html
+title: Water takes about a minute to seep from the soil surface to the drain hole.
+```
+````
+
+Rules:
+
+- `src` must be a local `.html` or `.pdf` in that same-name directory. It cannot point to `assets/`, another post, or `https://`
+- HTML that reports its height with `garden-chart` is a chart and is shown inline. Plain HTML and PDF are folded into a preview entry by default and load when the reader opens them
+- `title` must be a claim, not "see the chart below"
+- One chart per HTML file. Use short kebab-case names such as `layers.html` or `diagram.html`
+- The HTML is self-contained: CSS, SVG and scripts all live in that one file
+- Write the HTML first, then the fence. Do not spell out step arrays or sample points in the fence
+
+The build checks the path and copies the file to `/media/...`. A wrong path fails the build.
+
+## Writing the HTML
+
+1. Copy [references/shell.html](references/shell.html), or start from the closest example.
+2. Use only the color and font tokens in [references/style.md](references/style.md). Do not invent a dark cinematic style.
+3. Call the boot script in the shell: it reads `?theme=light|dark` and uses `ResizeObserver` to send `{ source: "garden-chart", height }` to the parent page.
+4. Respect `prefers-reduced-motion: reduce`: autoplay stops at the first step or the final state.
+5. Use native `button` and `input` controls. Bind sliders to fixed inputs. Never `eval` reader input, and never make network requests.
+6. Open the HTML in a browser and walk the main path and the empty state. Then run `CONTENT_INCLUDE_DRAFTS=1 make dev` to check the embed.
+
+## Don't
+
+- Put steps, grids or formula sample points in Markdown
+- Use remote scripts, remote iframes or any CDN (the system monospace stack is enough)
+- Read or write the parent page's DOM or cookies, or depend on `allow-same-origin`
+- Use MDX, JSX, or post-specific type names (for example `autoregressive-waste`)
+- Make the interaction the only explanation: the surrounding prose must stand on its own
+
+## Before you hand it in
+
+- [ ] The file is in the same-name directory, and the fence has only `src` + `title`
+- [ ] The HTML works when opened on its own, and the iframe grows to its height
+- [ ] Light and dark themes both follow the Garden page
+- [ ] No autoplay loop when reduced motion is on
+- [ ] `title` gives the conclusion to readers without JS

package/templates/skills-en/garden-interactive-chart/references/shell.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Chart title</title>
+  <style>
+    :root {
+      --paper: #f8f8f6; --paper-deep: #eeeeeb; --ink: #202124; --ink-soft: #34383d;
+      --muted: #65707d; --faint: #a1a6ad; --line: #deded9; --accent: #d82d48;
+      --accent-soft: #f9e8eb; --new: #1f7a4d; --new-soft: #e5f4ec;
+    }
+    :root[data-theme="dark"] {
+      --paper: #171819; --paper-deep: #202224; --ink: #ededeb; --ink-soft: #d8d8d4;
+      --muted: #a6adb6; --faint: #747b84; --line: #35383b; --accent: #ff5d76;
+      --accent-soft: #3b242a; --new: #5ee0a0; --new-soft: #1a3a2c;
+    }
+    html, body { margin: 0; background: var(--paper); color: var(--ink); }
+    body {
+      font: 13px/1.5 ui-monospace, "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+      padding: 16px;
+    }
+  </style>
+</head>
+<body>
+  <!-- Chart body -->
+  <script>
+    function gardenChartBoot() {
+      const theme = new URLSearchParams(location.search).get("theme");
+      if (theme === "dark" || theme === "light") {
+        document.documentElement.setAttribute("data-theme", theme);
+      }
+      const report = () => {
+        if (window.parent === window) return;
+        const height = Math.ceil(Math.max(
+          document.body.scrollHeight,
+          document.body.offsetHeight,
+          document.documentElement.scrollHeight,
+        ));
+        window.parent.postMessage({ source: "garden-chart", height }, "*");
+      };
+      new ResizeObserver(report).observe(document.body);
+      window.addEventListener("load", report);
+      requestAnimationFrame(() => requestAnimationFrame(report));
+    }
+    gardenChartBoot();
+  </script>
+</body>
+</html>