hd-garden 0.3.8 → 0.3.10

package/ui/preview/index.tsx

@@ -0,0 +1,191 @@
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { CATALOG_VERSION, COMPONENT_NAMES } from "../core/catalog.mjs";
+import { compileUiBlock } from "../core/compile.mjs";
+import { scanFences, splitUiBody } from "../core/fence.mjs";
+import { parseUiBody } from "../core/parse.mjs";
+import { renderStatic } from "../core/static.mjs";
+import { collectDataSources } from "../core/transform.mjs";
+import { suggestComponent } from "../core/validate.mjs";
+import { CatalogPage, type RecipeSource } from "../react/CatalogPage";
+import { IntentCard, UiErrorCard, UiFigure, type Diagnostic, type UiPayload } from "../react/index";
+
+export type PreviewOptions = {
+  theme?: "light" | "dark";
+  mode?: "interactive" | "static";
+  /** Reads a path relative to the Markdown file, for Data files. */
+  readFile?: (relativePath: string) => Promise<string | undefined> | string | undefined;
+  /** Same-name-directory path as written, mapped to a URL the host can display. */
+  resolveAsset?: (relativePath: string) => string;
+  /** Keep clicks and keys on controls from reaching the editor, which would otherwise jump into the source. */
+  isolateEvents?: boolean;
+  /** File line of the opening fence, so errors cite the line numbers the editor shows. */
+  fenceLine?: number;
+};
+
+type ParsedNode = { t: string; n?: string; c?: ParsedNode[] };
+
+/** A name with no close catalog match is likely newer than this plugin rather than a typo. */
+function hasNewerComponent(body: string) {
+  const { bodyText, error } = splitUiBody(body);
+  if (error) return false;
+  const { root } = parseUiBody(bodyText) as { root: ParsedNode | null };
+  const known = new Set<string>(COMPONENT_NAMES);
+  const unknown: string[] = [];
+  const walk = (node: ParsedNode) => {
+    if (node.t === "el" && node.n && !known.has(node.n)) unknown.push(node.n);
+    node.c?.forEach(walk);
+  };
+  if (root) walk(root);
+  return unknown.some((name) => !suggestComponent(name));
+}
+
+const CONTROLS = "input, button, select, textarea, a, [role='button'], [role='slider'], [role='tab'], [role='checkbox'], [tabindex]";
+const ISOLATED_EVENTS = ["pointerdown", "mousedown", "mouseup", "click", "keydown", "keyup", "keypress", "input", "beforeinput"];
+
+function isolate(element: HTMLElement) {
+  const stop = (event: Event) => {
+    const target = event.target;
+    if (target instanceof Element && target.closest(CONTROLS)) event.stopPropagation();
+  };
+  for (const type of ISOLATED_EVENTS) element.addEventListener(type, stop);
+  return () => {
+    for (const type of ISOLATED_EVENTS) element.removeEventListener(type, stop);
+  };
+}
+
+/** Accepts either a whole fence or just its body, as editors hand over either. */
+function bodyOf(source: string) {
+  const trimmed = source.replace(/^\s+/u, "");
+  if (/^(`{3,}|~{3,})/u.test(trimmed)) {
+    const fence = scanFences(trimmed)[0];
+    if (fence) return fence.body;
+  }
+  return source;
+}
+
+function Preview({ source, options }: { source: string; options: PreviewOptions }) {
+  const body = bodyOf(source);
+  const sources = collectDataSources(`\`\`\`ui\n${body}\n\`\`\``);
+  const sourcesKey = sources.join("\n");
+  const [files, setFiles] = useState<{ key: string; data: Record<string, string> }>({ key: "", data: {} });
+
+  useEffect(() => {
+    if (!sourcesKey || !options.readFile) return;
+    let active = true;
+    const read = options.readFile;
+    Promise.all(sourcesKey.split("\n").map(async (src) => [src, await read(src)] as const)).then((entries) => {
+      if (!active) return;
+      const data: Record<string, string> = {};
+      for (const [src, text] of entries) if (typeof text === "string") data[src] = text;
+      setFiles({ key: sourcesKey, data });
+    });
+    return () => {
+      active = false;
+    };
+  }, [sourcesKey, options.readFile]);
+
+  const loading = Boolean(sourcesKey && options.readFile && files.key !== sourcesKey);
+  const { payload, check } = compileUiBlock(body, {
+    lineOffset: options.fenceLine ?? 1,
+    readData: (src: string) => files.data[src],
+    skipData: !options.readFile,
+    markdownPath: null,
+    resolveAsset: null,
+  });
+  const theme = options.theme ?? "light";
+  if (loading) return <div className="garden-ui-preview" data-theme={theme}><p className="garden-ui-preview-note">正在读取数据文件…</p></div>;
+  if (!payload) {
+    const diagnostics = (check.diagnostics as Diagnostic[]).filter((item) => item.severity === "error");
+    const newer = diagnostics.some((item) => item.code === "ui-component") && hasNewerComponent(body);
+    const header = (check as { header?: { id?: unknown; caption?: unknown } | null }).header;
+    return (
+      <div className="garden-ui-preview" data-theme={theme}>
+        {newer ? <p className="garden-ui-preview-note">块里有这个插件不认识的组件，预览需要更新 Garden 插件。</p> : null}
+        <UiErrorCard
+          caption={typeof header?.caption === "string" ? header.caption : ""}
+          diagnostics={diagnostics}
+          id={typeof header?.id === "string" ? header.id : null}
+        />
+      </div>
+    );
+  }
+  const typed = payload as UiPayload;
+  if (options.resolveAsset) {
+    const rewrite = (node: UiPayload["root"]): UiPayload["root"] => {
+      if (node.t === "el" && node.n === "Image" && node.p?.src?.k === "lit") {
+        return { ...node, p: { ...node.p, src: { k: "lit", v: options.resolveAsset?.(String(node.p.src.v)) } } };
+      }
+      return node.c ? { ...node, c: node.c.map(rewrite) } : node;
+    };
+    typed.root = rewrite(typed.root);
+  }
+  const stale = (check.diagnostics as Diagnostic[]).some((item) => item.code === "ui-stale");
+  return (
+    <div className="garden-ui-preview" data-theme={theme}>
+      {stale ? <p className="garden-ui-preview-note">原话改过了，还没重编译。</p> : null}
+      {options.mode === "static" ? (
+        <figure className="garden-ui" lang="en-US">
+          <div className="garden-ui-body garden-ui-static" dangerouslySetInnerHTML={{ __html: renderStatic(typed, "html") }} />
+          <figcaption>{typed.caption}</figcaption>
+        </figure>
+      ) : (
+        <UiFigure payload={typed} />
+      )}
+    </div>
+  );
+}
+
+function mount(element: HTMLElement, draw: (root: ReturnType<typeof createRoot>) => void) {
+  const root = createRoot(element);
+  draw(root);
+  return root;
+}
+
+export function render(element: HTMLElement, source: string, options: PreviewOptions = {}) {
+  let current = { source, options };
+  const release = options.isolateEvents ? isolate(element) : null;
+  const root = mount(element, (target) => target.render(<Preview source={current.source} options={current.options} />));
+  return {
+    update(nextSource: string, nextOptions: PreviewOptions = current.options) {
+      current = { source: nextSource, options: nextOptions };
+      root.render(<Preview source={current.source} options={current.options} />);
+    },
+    destroy() {
+      release?.();
+      root.unmount();
+    },
+  };
+}
+
+type IntentOptions = { id?: string | null; theme?: "light" | "dark"; onCopyPrompt?: () => void; isolateEvents?: boolean };
+
+export function renderIntent(element: HTMLElement, text: string, options: IntentOptions = {}) {
+  const release = options.isolateEvents ? isolate(element) : null;
+  const draw = (nextText: string, next: IntentOptions) => (
+    <div className="garden-ui-preview" data-theme={next.theme ?? "light"}>
+      <IntentCard text={bodyOf(nextText).trim()} id={next.id} onCopyPrompt={next.onCopyPrompt} />
+    </div>
+  );
+  let current = options;
+  const root = mount(element, (target) => target.render(draw(text, current)));
+  return {
+    update(nextText: string, nextOptions: IntentOptions = current) {
+      current = nextOptions;
+      root.render(draw(nextText, current));
+    },
+    destroy() {
+      release?.();
+      root.unmount();
+    },
+  };
+}
+
+export function renderCatalog(element: HTMLElement, options: { recipes?: RecipeSource[]; theme?: "light" | "dark"; onStart?: (fence: string) => void } = {}) {
+  if (options.theme) element.setAttribute("data-theme", options.theme);
+  const root = mount(element, (target) => target.render(<CatalogPage recipes={options.recipes ?? []} onStart={options.onStart} />));
+  return { destroy: () => root.unmount() };
+}
+
+export const catalogVersion = CATALOG_VERSION;
+export { intentFence, STARTERS as starters } from "../core/starters.mjs";

package/ui/preview/mermaid-shim.ts

@@ -0,0 +1,19 @@
+// Editor hosts (Obsidian, Typora) ship their own Mermaid; the preview bundle uses it instead of bundling a copy.
+type MermaidLike = {
+  initialize: (config: Record<string, unknown>) => void;
+  render: (id: string, source: string) => Promise<{ svg: string }>;
+};
+
+const host = () => (globalThis as { mermaid?: MermaidLike }).mermaid;
+
+const mermaid: MermaidLike = {
+  // The host owns its Mermaid configuration; re-initializing would restyle the host's own diagrams.
+  initialize() {},
+  render(id, source) {
+    const instance = host();
+    if (!instance) return Promise.reject(new Error("这个编辑器没有提供 Mermaid"));
+    return instance.render(id, source);
+  },
+};
+
+export default mermaid;

package/ui/prompt/build.mjs

@@ -0,0 +1,24 @@
+import { catalogReference } from "../core/catalog.mjs";
+
+export const RECIPE_FILES = [
+  "param-bench.md",
+  "stepper.md",
+  "inspect-grid.md",
+  "compare.md",
+  "trace.md",
+  "converter.md",
+  "plan.md",
+  "data-chart.md",
+  "code-walkthrough.md",
+];
+
+/**
+ * `garden ui prompt`: rules + component reference generated from the catalog
+ * + recipes. The admin workbench appends `studio` for its output contract.
+ * @param {{ rules: string, recipes: string[], studio?: string | null }} parts
+ */
+export function buildPrompt({ rules, recipes, studio = null }) {
+  const parts = [rules.trim(), catalogReference().trim(), "## 配方", ...recipes.map((recipe) => recipe.trim())];
+  if (studio) parts.push(studio.trim());
+  return `${parts.join("\n\n---\n\n")}\n`;
+}

package/ui/prompt/recipes/code-walkthrough.md

@@ -0,0 +1,68 @@
+# 配方：代码走查
+
+**读者卡在哪：** 代码是一张照片。读者看不出"这一步执行到哪一行、变量此刻是多少"。
+
+**什么时候用：** 一段不长的代码（不超过 60 行），值得一行行讲：二分查找、锁的实现、状态机的处理函数。
+
+**什么时候不用：** 只需要展示代码（写普通代码块）；代码太长（只截关键的一段）。
+
+**作者可能这样说：** "一行行讲这段代码""每一步执行到哪""标出当前行，旁边列出变量"。
+
+**骨架（阶段 6 之前）：** 正文里先放普通代码块；这一块用 `Steps bind="step"` 讲每一步，配一张 `Table` 列出变量此刻的值，这一步变了的标成 `new`。阶段 6 起，用 `Code` 把代码放进块里，`highlight` 随步骤变化。
+
+阶段 6 之前：
+
+````md
+```ui
+---
+id: binary-search-vars
+caption: 每比较一次，搜索区间就缩小一半；8 个元素最多比较 4 次。
+intent: |
+  在 [1 3 5 7 9 11 13 15] 里找 9，一步步列出 lo、hi、mid 和比较结果。
+---
+<State step={0} />
+<Let los={[0, 4, 4]} his={[7, 7, 4]} mids={[3, 5, 4]} prev={max(step - 1, 0)} />
+
+<Steps bind="step">
+  <Step title="第 1 次">mid = 3，a[3] = 7 小于 9，目标在右半边。</Step>
+  <Step title="第 2 次">lo 移到 4；mid = 5，a[5] = 11 大于 9，目标在左半边。</Step>
+  <Step title="第 3 次">hi 移到 4；mid = 4，a[4] = 9，找到。</Step>
+</Steps>
+
+<Table columns={["lo", "hi", "mid"]}>
+  <Row cells={[los[step], his[step], mids[step]]}
+       tones={step == 0 ? "plain" : [los[step] != los[prev] ? "new" : "plain", his[step] != his[prev] ? "new" : "plain", "new"]} />
+</Table>
+```
+````
+
+阶段 6 起，在同一块里加上：
+
+```text
+<Code lang="go" highlight={["4-5", "6-7", "8-10"][step]} code={`func search(a []int, x int) int {
+	lo, hi := 0, len(a)-1
+	for lo <= hi {
+		mid := (lo + hi) / 2
+		if a[mid] < x {
+			lo = mid + 1
+		} else if a[mid] > x {
+			hi = mid - 1
+		} else {
+			return mid
+		}
+	}
+	return -1
+}`} />
+```
+
+**要点：**
+
+- 每一步的变量值写成数组，用 `step` 取下标；值必须和代码真实执行的结果一致，自己先在心里跑一遍。
+- 每一步的话说清"为什么走这一行"，不要只念代码。
+- 代码超过 60 行时只截关键的函数。
+
+**常见错误：**
+
+- 变量值和代码执行结果对不上（`hi` 的更新写错一步）。
+- 第 0 步就把变量标成 `new`。
+- 阶段 6 之前写了 `Code`。

package/ui/prompt/recipes/compare.md

@@ -0,0 +1,48 @@
+# 配方：对照
+
+**读者卡在哪：** 两种做法只能上下翻着看，工作记忆装不下"左边这样、右边那样"。
+
+**什么时候用：** 两三种方案在同一个输入下的表现差别：Mutex 和 RwLock、MHA 和 GQA、朴素实现和带缓存的实现、ECB 和 CBC。
+
+**什么时候不用：** 只是罗列各自的特点，没有共同的输入（写一张 Markdown 表格就够）。
+
+**作者可能这样说：** "并排对比""左右各放一个""同样的条件下谁更快"。
+
+**骨架：** `Columns` 里放两个 `Card`，两边读同一个状态；共同的输入（`Slider`、`Toggle`）放在上面。想强调胜出的一方时，给它 `tone="accent"`。
+
+````md
+```ui
+---
+id: mutex-vs-rwlock
+caption: 读者越多，Mutex 越慢；RwLock 让读者并行，总耗时不变。
+intent: |
+  对比 Mutex 和 RwLock：读者数量 1 到 8 可调，一个写者，每次读写 10 ms，看总耗时。
+expect:
+  - given: { readers: 3 }
+    mutexMs: 40
+    rwMs: 20
+---
+<State readers={3} />
+<Let mutexMs={(readers + 1) * 10} rwMs={20} />
+
+<Slider bind="readers" label="同时到达的读者" min={1} max={8} unit="个" />
+
+<Columns>
+  <Card title="Mutex">读者和写者一个接一个，共 **{mutexMs} ms**。</Card>
+  <Card title="RwLock" tone="accent">{readers} 个读者一起读，写者再独占，共 **{rwMs} ms**。</Card>
+</Columns>
+```
+````
+
+**要点：**
+
+- 两边的结构保持一致：同样的组件、同样的顺序，只有数字和措辞不同。
+- 共同输入只放一份，不要每边各放一个滑杆。
+- 窄屏上 `Columns` 会自动上下叠放，两边的文字要能各自读懂。
+- 两边都要算的量写进 `Let`，并为它们写 `expect`。
+
+**常见错误：**
+
+- 两边读的不是同一个状态，读者拧一边，另一边不动。
+- 放了三个以上的 `Card`，变成罗列。
+- 把"哪边更好"的结论只写在颜色里；结论要写进 `caption`。

package/ui/prompt/recipes/converter.md

@@ -0,0 +1,55 @@
+# 配方：换算器
+
+**读者卡在哪：** 一组量都跟着同一个数变化，作者只能给一两个例子，读者的情况往往不在其中。
+
+**什么时候用：** 一个输入驱动好几个输出：按人数换算用料、按并发数换算资源、按规模换算成本、按单位换算。
+
+**什么时候不用：** 只有一个输出（用参数台）；输出之间要分别调（先拆块）。
+
+**作者可能这样说：** "按人数算要买多少""换算表""不同规模下各要多少"。
+
+**骨架：** 一个 `Slider` 或 `Choice` 作为输入；把每一项的单位用量写进 `Let` 数组；`Table` 里用 `Each` 逐项生成行。
+
+````md
+```ui
+---
+id: roast-shopping
+caption: 用料按人数线性换算；带骨羊腿每人 0.4 kg。
+intent: |
+  按人数（2 到 12 人，默认 6 人）算周日烤羊腿要买多少：
+  带骨羊腿每人 0.4 kg，土豆每人 250 g，胡萝卜每人 1.5 根，甜点苹果每人半个。
+expect:
+  - given: { guests: 6 }
+    lamb: 2.4
+---
+<State guests={6} />
+<Let lamb={0.4 * guests}
+     items={[
+       { name: "土豆", per: 250, unit: "g" },
+       { name: "胡萝卜", per: 1.5, unit: "根" },
+       { name: "苹果（甜点）", per: 0.5, unit: "个" },
+     ]} />
+
+<Slider bind="guests" label="人数" min={2} max={12} unit="人" />
+
+<Table columns={[{ label: "食材" }, { label: "数量", align: "right" }]}>
+  <Row cells={["带骨羊腿", fixed(lamb, 1) + " kg"]} tones="accent" />
+  <Each of={items} as="it">
+    <Row cells={[it.name, ceil(it.per * guests) + " " + it.unit]} />
+  </Each>
+</Table>
+```
+````
+
+**要点：**
+
+- 每一项的单位用量都来自原话；原话没给的项不要加。
+- 按个数计的东西用 `ceil` 向上取整，按重量计的用 `fixed` 保留一位小数。
+- 最关键的那一项可以单独写一行并标 `accent`，同时为它写 `expect`。
+- 输入是几个离散档位（比如"小 / 中 / 大"）时，用 `Choice` 代替 `Slider`。
+
+**常见错误：**
+
+- 用 `.map()` 生成行，而不是 `Each`。
+- 按个数计的东西算出 7.5 个。
+- 表格里堆了原话没提到的项。

package/ui/prompt/recipes/data-chart.md

@@ -0,0 +1,57 @@
+# 配方：数据图
+
+**读者卡在哪：** 测出来的数字被贴成一张截图，读者看不清具体值，也没法对照。
+
+**什么时候用：** 作者手里有一组实测数据：压测结果、基准测试、实验记录。
+
+**什么时候不用：** 数据可以由公式算出（用参数台）；只有两三个数（写进句子）。
+
+**作者可能这样说：** "把这组压测数据画出来""柱状图对比""数据在 xxx.csv 里"。
+
+**骨架：** 原话里直接给了数字时，用 `Let` 数组照抄；原话提到同名目录里的文件时，用 `Data`。`Chart data` 画图，`Table data` 列出精确值。
+
+下面的数字只是示例；真实的块里，每个数字都必须来自原话或数据文件。
+
+````md
+```ui
+---
+id: redis-io-threads
+caption: I/O 线程从 1 加到 4，QPS 涨了两倍多；再加到 8，只多了一成多。
+intent: |
+  把 Redis I/O 线程数的压测结果画成柱状图，再列一张表：
+  1 线程 98000，2 线程 181000，4 线程 312000，8 线程 356000。
+---
+<Let bench={[
+  { threads: 1, qps: 98000 },
+  { threads: 2, qps: 181000 },
+  { threads: 4, qps: 312000 },
+  { threads: 8, qps: 356000 },
+]} />
+
+<Chart data={bench} x={threads} xLabel="I/O 线程" yLabel="QPS" yFormat="si">
+  <Bar y={qps} label="QPS" />
+</Chart>
+
+<Table data={bench} rowTone={threads == 4 ? "accent" : null}
+       columns={[{ label: "I/O 线程", key: "threads" }, { label: "QPS", key: "qps", format: "thousands" }]} />
+```
+````
+
+数据在文件里时，把 `Let` 换成：
+
+```text
+<Data name="bench" src="./redis-bench/bench.csv" />
+```
+
+**要点：**
+
+- 数字一个都不能改，也不能"顺手"补全缺的点。
+- 离散的类别（线程数、版本号）用 `Bar`；连续变量的趋势用 `Line`。
+- 想说明的拐点用 `rowTone` 在表里标出来，结论写进 `caption`。
+- 要让读者在两组数据间切换时，加一个 `Choice`，`data` 用三元选择。
+
+**常见错误：**
+
+- 编造原话里没有的数据点。
+- 原话已经给了完整数字，却还去引用一个并不存在的文件。
+- 横轴是类别却用了 `Line`，暗示中间存在连续值。

package/ui/prompt/recipes/inspect-grid.md

@@ -0,0 +1,45 @@
+# 配方：检视格
+
+**读者卡在哪：** 二维结构被压成了表格或图片。Attention 分数、页锁 bitmap、加密块，本质上是格子，可格子不会说话。
+
+**什么时候用：** 读者需要盯着某几格看，并且知道"这一格为什么特别"。ECB 的重复块、Attention 矩阵、缓存命中情况、二分查找里 lo / mid / hi 的位置。
+
+**什么时候不用：** 只是一份普通的数据表，没有哪一格需要特别解释（用 `Table`，或者干脆写 Markdown 表格）。
+
+**作者可能这样说：** "让读者点格子看解释""标出哪些块是重复的""矩阵里高亮这几格"。
+
+**骨架：** `Grid` + 每行一个 `Row`；用 `tones` 标出特别的格子，用 `notes` 写每格的话，用 `legend` 解释颜色。需要切换场景时，加一个 `Choice` 或 `Toggle`。
+
+````md
+```ui
+---
+id: ecb-vs-cbc
+caption: ECB 下相同的明文块得到相同的密文块；CBC 把上一块的密文混进来，重复就消失了。
+intent: |
+  明文四块 A B A A，让读者在 ECB 和 CBC 之间切换，看密文里重复的块。
+---
+<State mode="ecb" />
+
+<Choice bind="mode" label="模式" options={[{ value: "ecb", label: "ECB" }, { value: "cbc", label: "CBC" }]} />
+
+<Grid cols={["块1", "块2", "块3", "块4"]} legend={{ same: "密文与别的块相同" }}>
+  <Row label="明文" cells={["A", "B", "A", "A"]} />
+  <Row label="密文" cells={mode == "ecb" ? ["X", "Y", "X", "X"] : ["P", "Q", "R", "S"]}
+       tones={mode == "ecb" ? ["same", "plain", "same", "same"] : "plain"}
+       notes={mode == "ecb" ? ["和块3、块4相同", "", "和块1相同", "和块1相同"] : ["", "", "", ""]} />
+</Grid>
+```
+````
+
+**要点：**
+
+- 颜色只用来标"特别"的格子，其余保持 `plain`。
+- `notes` 写"这格为什么这样"，不要重复格子里的值。
+- 格子里放短内容（1–4 个字符）；长内容放进 `notes`。
+- 超过 16 × 16 时，只截出能说明问题的那一角。
+
+**常见错误：**
+
+- `cells`、`tones`、`notes` 长度和 `cols` 对不上。
+- 整张格子都上色，读者不知道该看哪里。
+- 用 `Grid` 摆一份普通数据表。

package/ui/prompt/recipes/param-bench.md

@@ -0,0 +1,55 @@
+# 配方：参数台
+
+**读者卡在哪：** 公式是活的，页面上的数字是死的。作者算好了一组结果，读者想换个参数只能自己掏计算器。
+
+**什么时候用：** 结果由一两个输入决定，而且读者会好奇"换成别的值会怎样"。KV cache 显存、浮点精度、学习率曲线、复利、哈希表装载因子。
+
+**什么时候不用：** 只有一个固定的例子要讲；或者输入超过 3 个，读者拧不过来（先拆块）。
+
+**作者可能这样说：** "让读者拧 batch 和序列长度""拖一下看看""从 1 到 32 可调""看曲线怎么变"。
+
+**骨架：** `State` 放输入，`Let` 写公式，`Slider` 绑输入，一句带插值的话说出当前结果，需要看趋势时加 `Chart sweep`。
+
+````md
+```ui
+---
+id: kv-memory
+caption: 显存与 batch、序列长度都成正比；batch 8、序列 32K 就要 32 GiB。
+intent: |
+  让读者拧 batch 和序列长度，看 KV cache 占多少显存。
+  batch 1 到 32，默认 1；序列 1K 到 32K，默认 4K，用对数轴。
+  显存 = 2 × 32 层 × 8 个 KV 头 × 128 维 × 序列长度 × batch × 2 字节。
+  batch 1、序列 4096 时是 512 MiB。
+expect:
+  - given: { batch: 1, seq: 4096 }
+    mem: 536870912
+---
+<State batch={1} seq={4096} />
+<Let mem={2 * 32 * 8 * 128 * seq * batch * 2} />
+
+<Columns>
+  <Slider bind="batch" label="batch" min={1} max={32} />
+  <Slider bind="seq" label="序列长度" min={1024} max={32768} scale="log" format="thousands" />
+</Columns>
+
+batch 为 {batch}、序列 {thousands(seq)} 时，KV cache 要 **{bytes(mem)}**。
+
+<Chart sweep="seq" yLabel="KV 显存">
+  <Line y={mem} label="KV 显存" format="bytes" />
+</Chart>
+```
+````
+
+**要点：**
+
+- 一句会变的话通常比一个孤零零的 `Stat` 更好读；要强调单个数字时才用 `Stat`。
+- 横轴跨好几个数量级时用 `scale="log"`；端点都是 2 的幂时，滑杆自动只停在 2 的幂上。
+- 横轴不是任何滑杆时（比如训练步数），先 `<State t={0} />`，再写 `<Chart sweep="t" from={0} to={10000}>`。
+- 想和容量上限比，加一个 `Meter`。
+- 原话里有已知点，一定写 `expect`。
+
+**常见错误：**
+
+- 公式里的常数和原话对不上（层数、头数抄错）。
+- 对数滑杆的 `min` 写成 0。
+- 两根滑杆都画在 `Chart` 的横轴上：`sweep` 只能是一个状态，另一个保持当前值。

package/ui/prompt/recipes/plan.md

@@ -0,0 +1,45 @@
+# 配方：计划与清单
+
+**读者卡在哪：** 步骤多、要跟着做，读者一边操作一边回来找"做到哪了"。
+
+**什么时候用：** 部署步骤、排查清单、做菜时间线、迁移步骤。读者真的会照着一项项做。
+
+**什么时候不用：** 只是概念上的几个阶段（写列表）；步骤之间有状态变化要观察（用步进器）。
+
+**作者可能这样说：** "给一张可勾选的清单""照着一步步做""时间线"。
+
+**骨架：** 一个 `Checklist`，每项写清时间或顺序、要做什么、注意什么。前面可以放一个决定清单内容的输入。
+
+````md
+```ui
+---
+id: roast-timeline
+caption: 大部分活都在客人到之前做完；开饭前一小时只剩烤土豆和做肉汁。
+intent: |
+  给一张周日烤羊腿的时间线清单，假设 5 点开饭，让读者一项项勾掉。
+---
+<Checklist title="周日时间线" items={[
+  { time: "前一天", title: "做好苹果酥，腌羊腿", note: "盐、蒜、迷迭香、橄榄油，冷藏过夜" },
+  { time: "12:30", title: "羊腿出冰箱回温" },
+  { time: "13:30", title: "羊腿进烤箱", note: "用温度计判断熟度，不要只看时间" },
+  { time: "14:30", title: "土豆焯水、沥干、摇出毛边" },
+  { time: "15:30", title: "羊腿出炉静置，烤土豆和蔬菜" },
+  { time: "16:15", title: "做肉汁，烫青菜" },
+  { time: "16:45", title: "切肉装盘" },
+  { time: "17:00", title: "开饭，苹果酥回炉加热" },
+]} />
+```
+````
+
+**要点：**
+
+- 每一项以动作开头（"腌""切""检查"），不要写成名词。
+- 注意事项放进 `note`，不要塞进 `title`。
+- 清单里的时间和数量来自原话；原话只给了开饭时间时，可以按常识倒推，但要在回复里说明哪些是推出来的。
+- 读者需要先选一个参数（人数、环境）时，前面加一个 `Choice`，`items` 用三元在两套清单间切换。
+
+**常见错误：**
+
+- 超过 30 项（拆成准备、当天两块）。
+- 把要观察的过程写成清单。
+- 想让勾选状态影响别的组件：`Checklist` 不能绑定。

package/ui/prompt/recipes/stepper.md

@@ -0,0 +1,52 @@
+# 配方：步进器
+
+**读者卡在哪：** 过程被拍成了一张图。读者没法停在第 3 步，也没法问"再走一步，哪里变了"。
+
+**什么时候用：** 状态随时间变化的机制：Prefill / Decode、反向传播、Raft 选举、GC 三色标记、锁的获取与释放、算法的每一轮。
+
+**什么时候不用：** 只有两三个静态阶段，一张 Mermaid 或一个列表就能说清；步骤之间没有"状态在变"这件事。
+
+**作者可能这样说：** "让读者一步步看""停在某一拍""每步标出新算的是哪一行""第几轮发生了什么"。
+
+**骨架：** `State step={0}`，`Steps bind="step"` 里每步一句话；旁边放一个随 `step` 变化的 `Grid` 或 `Table`，把这一步变了的地方标成 `new`。
+
+````md
+```ui
+---
+id: prefill-decode
+caption: Prefill 一次写满 3 行 K/V；之后每步只新算 1 行，其余读缓存。
+intent: |
+  让读者一步步看 KV cache 怎么增长：prompt 3 个 token，再 decode 两步。
+  每步标出哪一行是新算的，哪些是读缓存。
+---
+<State step={0} />
+<Let rows={step + 3} />
+
+<Steps bind="step">
+  <Step title="Prefill">一次算完 3 个 prompt token 的 K/V，全部写进缓存。</Step>
+  <Step title="Decode 1">新 token 只算自己的 K/V，追加第 4 行；前 3 行直接读缓存。</Step>
+  <Step title="Decode 2">再追加一行。缓存里已有 {rows} 行，本步新算 1 行。</Step>
+</Steps>
+
+<Grid cols={["K", "V"]} legend={{ new: "本步新算", cached: "读缓存" }}>
+  <Each of={range(0, rows)} as="i">
+    <Row label={"t" + (i + 1)} cells={["k" + (i + 1), "v" + (i + 1)]}
+         tones={step == 0 || i == rows - 1 ? "new" : "cached"} />
+  </Each>
+</Grid>
+```
+````
+
+**要点：**
+
+- 每步的话只说这一步变了什么，一两句。
+- 想让别的组件跟着步骤变，`Steps` 必须写 `bind`；只是翻页看文字时可以不写。
+- 每一步的数据用 `step` 推出来（`Let`、三元、数组下标），不要为每一步复制一份 `Grid`。
+- 末步做"前后对比"时，可以在最后一个 `Step` 里放 `Columns`。
+- 一般不开 `autoplay`；读者自己翻更容易停下来想。
+
+**常见错误：**
+
+- 超过 12 步还硬塞在一块里（先拆成两块）。
+- `Step` 里的话和旁边格子的状态对不上（第 2 步说"追加第 4 行"，格子却已有 5 行）。
+- 用 `Button set` 自己做上一步、下一步：`Steps` 已经带了。