用途：把一次改动或一段解释画成一张会动的图。你只写图表 JSON，不写 SVG；一条命令渲染，无需构建、无需浏览器。输出的单个 SVG 无脚本，凡能渲染 Markdown 的地方均可播放，缩放清晰，并跟随读者的亮/暗主题。
主要能力：图表采用 Giotto 格式（与文档站交互图表相同的 JSON）。元素是一张扁平列表：group 按 id 列出子元素并用 layout 排布（direction 为 row 或 column，可设 gap、align，label 可加标题框），rectangle 表示执行动作的框，cylinder 表示静态数据，diamond 表示判断；框内内容用 title、subtitle、text、list、chips、code 等块。arrow 用 start/end 指向框或组，可带 label，route 为 curved，around 取 above/below 跨过中间框，quiet 表示仅在某个场景使用它时才绘制。scenes 与 beats 控制动画：每个 scene 是一个故事并循环播放，每个 beat 可设置 edges（箭头、反向跳转或数据块）、say（字幕）、show（框内卡片，持续到本场景结束）、light（高亮）、ms（时长）。卡片行支持 tag、tone（blue/purple/green/orange/red/gray）、text、meta、mark、mono。
使用方式：先写图表 JSON。不要把它存进仓库当交付物，它只是输入。用 stdin 传给命令，渲染出的 SVG 会自行保留一份该 JSON：
npx giotto export - path/to/out.svg <<'DOC' { "title": …, "elements": […], "scenes": […] } DOC
其他形式：
npx giotto export hindsight-docs/figures/retain.json out.svg npx giotto export doc.json out.svg --theme dark --static npx giotto spec out.svg
giotto 来自文档站依赖（在仓库根目录执行 npm install）。布局与场景警告会打印在 stderr，应修复；引用了不存在的元素（箭头端点、组的子元素、场景填充的框）会报错并完全不输出文件。每个 SVG 会把图表嵌在 <metadata id="giotto-doc"> 里，因此无需保留 JSON 也能继续编辑：用 giotto spec 读回、修改后再次渲染。
发布前务必亲眼看一遍：先在 out.svg 所在目录启动 python3 -m http.server 8777（浏览器工具会拦截 file:// 链接），打开 http://localhost:8777/out.svg 截图，等几秒再截一次以捕捉后续节拍。放置位置：PR 或 issue 评论可把 SVG 提交到分支后引用其 raw URL；README 或仓库文档用相对路径链接；博客放在 hindsight-docs/static/img/blog/，以 /img/blog/<name>.svg 引用；文档站自己的页面不用 SVG，而用交互播放器（有标签页、暂停、倍速与悬停），把图保存为 hindsight-docs/figures/<name>.json 并通过 Figure 组件挂载。
限制：SVG 会循环播放所有场景且没有任何控件，没有标签页、暂停和悬停；若需要这些，应放到文档站。一张 SVG 建议只保留一两个场景，让循环尽快回到开头。标注、卡片和字幕必须与代码实际行为一致，不要凭假设填写。