hd-garden 0.6.0 → 0.7.0

package/app/styles/a2.css

@@ -1041,6 +1041,42 @@ html[data-theme="dark"] .markdown-body > p > img:not([class]) {
   color: var(--ink);
 }
 
+.g-cmp dl {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 10px 0 0;
+  padding-top: 10px;
+  border-top: 1px solid var(--rule);
+}
+
+.g-cmp dl > span {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 5px;
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--well);
+  font: 400 12px / 1.45 var(--sans);
+}
+
+.g-cmp dt {
+  margin: 0;
+  color: var(--muted);
+}
+
+.g-cmp dt::after {
+  content: "·";
+  margin-left: 5px;
+  color: var(--muted);
+}
+
+.g-cmp dd {
+  margin: 0;
+  font-weight: 500;
+  color: var(--ink);
+}
+
 .g-cmp p,
 .g-card p,
 .g-tl-x {
@@ -1698,3 +1734,498 @@ html[data-theme="dark"] .gf-scrim { background: rgb(0 0 0 / 45%); }
 .gf-db .gf-doc p, .gf-db .gf-doc li { font-size: 15px; line-height: 1.75; }
 .gf-db .gf-doc p { margin: 0 0 14px; }
 .gf-db .gf-doc ul, .gf-db .gf-doc ol { margin: 0 0 14px; }
+
+/* ===== Garden Handbook (/garden & /garden/[...slug]) ===== */
+
+.garden-doc-page {
+  width: min(1380px, calc(100% - 48px));
+  margin: 0 auto;
+  padding: 44px 0 112px;
+  display: grid;
+  grid-template-columns: 224px minmax(0, var(--col)) 188px;
+  gap: 0 24px;
+  align-items: start;
+  justify-content: space-between;
+  font-family: var(--sans);
+}
+
+.garden-doc-page .g-explore:not([data-sel="all"]) .dx-wrap [data-p]:not(.on),
+.garden-doc-page .g-explore:not([data-sel="all"]) .dx-wrap text:not(.on),
+.garden-doc-page .g-figure:not([data-sel="all"]) [data-p]:not(.on),
+.garden-doc-page .g-figure:not([data-sel="all"]) text:not(.on) {
+  opacity: 0.56;
+}
+
+.garden-doc-page > .toc {
+  margin-top: 8px;
+  position: sticky;
+  top: calc(var(--hdr) + 28px);
+  max-height: calc(100vh - var(--hdr) - 48px);
+  overflow-y: auto;
+  border-left: 0;
+  padding: 4px 0 24px;
+}
+
+/* Mobile chapter bar & backdrop (hidden on desktop) */
+.gdoc-mobile-bar,
+.gdoc-backdrop,
+.gdoc-mobile-close,
+.gdoc-nojs-trigger,
+.gdoc-nojs-close {
+  display: none;
+}
+
+/* Left Handbook Sidebar */
+.gdoc-sidebar {
+  position: sticky;
+  top: calc(var(--hdr) + 24px);
+  max-height: calc(100vh - var(--hdr) - 40px);
+  overflow-y: auto;
+  padding-right: 16px;
+  border-right: 1px solid var(--rule);
+  scrollbar-width: thin;
+}
+
+.gdoc-sidebar-head {
+  padding-bottom: 14px;
+  margin-bottom: 16px;
+  border-bottom: 1px solid var(--rule);
+}
+
+.gdoc-overview-link {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  padding: 8px 10px;
+  border-radius: 10px;
+  color: var(--ink);
+  text-decoration: none;
+  transition: background-color 0.15s ease;
+}
+
+.gdoc-overview-link:hover {
+  background: var(--tint);
+}
+
+.gdoc-overview-link[aria-current="page"] {
+  background: var(--well);
+}
+
+.gdoc-overview-mark {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font: 600 15px/1.3 var(--serif);
+  color: var(--ink);
+}
+
+.gdoc-overview-link small {
+  padding-left: 23px;
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--muted);
+}
+
+.gdoc-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.gdoc-nav-group-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 0 10px;
+  margin-bottom: 6px;
+}
+
+.gdoc-nav-group-head h2 {
+  margin: 0;
+  font: 600 12px/1.4 var(--sans);
+  letter-spacing: 0.02em;
+  color: var(--muted);
+}
+
+.gdoc-nav-group-head span {
+  font: 400 11px/1.3 var(--mono);
+  color: var(--muted);
+  opacity: 0.8;
+}
+
+.gdoc-nav-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.gdoc-nav-list li {
+  margin: 0;
+  padding: 0;
+}
+
+.gdoc-nav-list a {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-radius: 8px;
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--soft);
+  text-decoration: none;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+.gdoc-nav-list a:hover {
+  background: var(--tint);
+  color: var(--ink);
+}
+
+.gdoc-nav-list li.is-active a,
+.gdoc-nav-list a[aria-current="page"] {
+  background: var(--well);
+  color: var(--ink);
+  font-weight: 600;
+}
+
+.gdoc-comp-pill {
+  flex: none;
+  padding: 1px 6px;
+  border-radius: 5px;
+  border: 1px solid var(--rule-strong);
+  background: var(--card);
+  font: 500 12px/1.4 var(--mono);
+  color: var(--ink);
+}
+
+.gdoc-nav-list li.is-active .gdoc-comp-pill {
+  background: var(--ink);
+  border-color: var(--ink);
+  color: var(--paper);
+}
+
+.gdoc-comp-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Chapter Article Column */
+.garden-doc-article {
+  min-width: 0;
+  max-width: var(--col);
+  width: 100%;
+}
+
+.gdoc-article-head {
+  padding: 4px 0 28px;
+  margin-bottom: 32px;
+  border-bottom: 1px solid var(--rule);
+}
+
+.gdoc-eyebrow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 12px;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--muted);
+}
+
+.gdoc-eyebrow-root {
+  color: var(--soft);
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.gdoc-eyebrow-root:hover {
+  color: var(--ink);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.gdoc-eyebrow-fence {
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--well);
+  border: 1px solid var(--rule);
+  font: 500 12px/1.4 var(--mono);
+  color: var(--ink);
+}
+
+.gdoc-article-head h1 {
+  margin: 0;
+  font: 700 clamp(28px, 3.4vw, 38px) / 1.24 var(--sans);
+  color: var(--ink);
+  letter-spacing: -0.015em;
+  text-wrap: balance;
+}
+
+.gdoc-article-head h1.h1-br {
+  white-space: normal;
+  max-width: none;
+}
+
+@media (min-width: 768px) {
+  .gdoc-article-head h1.h1-br {
+    font-size: min(clamp(28px, 3.4vw, 38px), calc(min(100vw - 80px, 740px) / var(--l)));
+  }
+}
+
+.gdoc-article-deck {
+  margin: 14px 0 0;
+  font-size: 18px;
+  line-height: 1.65;
+  color: var(--soft);
+}
+
+.garden-doc-article .markdown-body h2:first-child {
+  margin-top: 8px;
+}
+
+/* Prev / Next Pager */
+.gdoc-pager {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+  margin-top: 64px;
+  padding-top: 28px;
+  border-top: 1px solid var(--rule);
+}
+
+.gdoc-pager-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 16px 18px;
+  border: 1px solid var(--rule);
+  border-radius: 12px;
+  background: var(--card);
+  text-decoration: none;
+  transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.gdoc-pager-card:hover {
+  border-color: var(--rule-strong);
+  background: var(--card-hover);
+}
+
+.gdoc-pager-card.is-next {
+  grid-column: 2;
+  text-align: right;
+  align-items: flex-end;
+}
+
+.gdoc-pager-dir {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.gdoc-pager-card strong {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.45;
+  color: var(--ink);
+}
+
+/* Responsive Breakpoints */
+@media (max-width: 1260px) {
+  .garden-doc-page {
+    grid-template-columns: 220px minmax(0, var(--col));
+    justify-content: center;
+    gap: 0 44px;
+  }
+
+  .garden-doc-page > .toc {
+    display: none;
+  }
+}
+
+@media (max-width: 1080px) {
+  .garden-doc-page {
+    display: block;
+    width: min(var(--col), calc(100% - 40px));
+    padding: 20px 0 88px;
+  }
+
+  .gdoc-mobile-bar {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 10px 14px;
+    margin-bottom: 24px;
+    border: 1px solid var(--rule);
+    border-radius: 10px;
+    background: var(--card);
+  }
+
+  .gdoc-mobile-trigger,
+  .gdoc-nojs-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    min-height: 34px;
+    padding: 0 12px;
+    border: 1px solid var(--rule-strong);
+    border-radius: 8px;
+    background: var(--well);
+    font: 600 13px/1 var(--sans);
+    color: var(--ink);
+    cursor: pointer;
+    white-space: nowrap;
+  }
+
+  .gdoc-nojs-trigger {
+    display: none;
+    text-decoration: none;
+  }
+
+  .gdoc-mobile-crumb {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    font-size: 13px;
+    color: var(--muted);
+  }
+
+  .gdoc-mobile-crumb > span,
+  .gdoc-mobile-crumb > svg {
+    flex-shrink: 0;
+    white-space: nowrap;
+  }
+
+  .gdoc-mobile-crumb strong {
+    min-width: 0;
+    color: var(--ink);
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .gdoc-backdrop {
+    display: block;
+    position: fixed;
+    inset: 0;
+    z-index: 82;
+    border: 0;
+    padding: 0;
+    background: rgb(20 20 19 / 34%);
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition: opacity 0.18s ease, visibility 0s linear 0.18s;
+  }
+
+  .gdoc-backdrop[data-open="true"] {
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+    transition: opacity 0.18s ease, visibility 0s;
+  }
+
+  .gdoc-sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    z-index: 84;
+    width: min(320px, 86vw);
+    max-height: none;
+    padding: 20px 18px 36px;
+    border-right: 1px solid var(--rule);
+    background: var(--paper);
+    box-shadow: 12px 0 36px rgb(0 0 0 / 14%);
+    transform: translateX(-104%);
+    visibility: hidden;
+    pointer-events: none;
+    transition: transform 0.2s ease, visibility 0s linear 0.2s;
+  }
+
+  .gdoc-sidebar[data-open="true"] {
+    transform: translateX(0);
+    visibility: visible;
+    pointer-events: auto;
+    transition: transform 0.2s ease, visibility 0s;
+  }
+
+  .gdoc-sidebar-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+  }
+
+  .gdoc-mobile-close {
+    display: inline-grid;
+    place-items: center;
+    width: 34px;
+    height: 34px;
+    border: 1px solid var(--rule);
+    border-radius: 50%;
+    background: var(--well);
+    color: var(--ink);
+  }
+}
+
+@media (max-width: 1080px) and (scripting: none) {
+  .gdoc-mobile-trigger,
+  .gdoc-mobile-close {
+    display: none;
+  }
+
+  .gdoc-nojs-trigger {
+    display: inline-flex;
+  }
+
+  .gdoc-nojs-close {
+    display: inline-grid;
+    place-items: center;
+    width: 34px;
+    height: 34px;
+    border: 1px solid var(--rule);
+    border-radius: 50%;
+    background: var(--well);
+    color: var(--ink);
+    text-decoration: none;
+  }
+
+  .gdoc-sidebar:target {
+    transform: translateX(0);
+    visibility: visible;
+    pointer-events: auto;
+  }
+}
+
+@media (max-width: 900px) {
+  .garden-doc-page > .toc {
+    display: flex;
+  }
+}
+
+@media (max-width: 720px) {
+  .gdoc-pager {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .gdoc-pager-card.is-next {
+    grid-column: 1;
+    text-align: left;
+    align-items: flex-start;
+  }
+}
+

package/docs/handbook/assets/reading-layout.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="2080" height="560" viewBox="0 0 1040 280" fill="none" font-family="-apple-system, BlinkMacSystemFont, 'PingFang SC', 'Noto Sans SC', sans-serif">
+  <!-- Outer 1340px wide-table boundary -->
+  <rect x="20" y="20" width="1000" height="240" rx="14" stroke="#6e6b64" stroke-width="1.5" stroke-dasharray="6 5" />
+  <text x="44" y="48" fill="#4a4844" font-size="13" font-weight="600">多列表格外扩区 · 文章页上限 1340px（单侧最多外扩 300px）</text>
+  <text x="996" y="48" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1340px</text>
+
+  <!-- Middle 1040px wide-figure boundary -->
+  <rect x="110" y="66" width="820" height="174" rx="12" stroke="#2d2c29" stroke-width="1.5" stroke-dasharray="4 4" />
+  <text x="132" y="92" fill="#2d2c29" font-size="13" font-weight="600">宽幅配图外扩区 · 文章页上限 1040px（截图按像素宽度的一半显示，超过 740px 才外扩）</text>
+  <text x="908" y="92" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1040px</text>
+
+  <!-- Inner 740px reading column -->
+  <rect x="215" y="110" width="610" height="110" rx="10" fill="#f0eee6" fill-opacity="0.72" stroke="#1b1a18" stroke-width="2" />
+  <text x="520" y="146" text-anchor="middle" fill="#1b1a18" font-size="16" font-weight="700">正文阅读列 · 740px（var(--col)）</text>
+  <text x="520" y="172" text-anchor="middle" fill="#2d2c29" font-size="13">段落、列表、引用、代码块与公式默认收敛在此列内</text>
+  <text x="520" y="196" text-anchor="middle" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">暗色模式透明底配图自动补 var(--image-backing) #faf9f5 暖白底</text>
+
+  <!-- Left & right expansion arrows -->
+  <path d="M210 165 H118" stroke="#2d2c29" stroke-width="1.5" />
+  <path d="M124 160 L116 165 L124 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+  <text x="164" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">≤ 150px</text>
+
+  <path d="M830 165 H922" stroke="#2d2c29" stroke-width="1.5" />
+  <path d="M916 160 L924 165 L916 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+  <text x="876" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">≤ 150px</text>
+</svg>

package/docs/handbook/components/card.md

@@ -0,0 +1,44 @@
+---
+title: 知识卡片（card）
+navTitle: 知识卡片
+description: 把论文、项目或模块说明整理成带元数据与编号要点的卡片。
+section: components
+order: 31
+badge: card
+---
+
+```garden card
+title: SQLite WAL 写入模式
+url: https://www.sqlite.org/wal.html
+meta: 文档说明 · sqlite.org
+description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
+points:
+  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
+  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
+  - 后台 Checkpoint 按阈值将日志页分批写回主库文件。
+```
+
+````markdown
+```garden card
+title: SQLite WAL 写入模式
+url: https://www.sqlite.org/wal.html
+meta: 文档说明 · sqlite.org
+description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
+points:
+  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
+  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
+  - 后台 Checkpoint 按阈值将日志页分批写回主库文件。
+```
+````
+
+- **用**：介绍一篇论文、一个开源项目或某个子系统，需要带出来源链接和 2～4 条关键要点时。
+- **别用**：只有一两句普通说明时直接写正文段落或链接卡片（`{card}`），不要套一层 `card`。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `title` | 建议 | 字符串 | 卡片标题 |
+| `url` | 否 | 完整链接 | 标题旁显示的外部链接（渲染为 `来源 ↗`） |
+| `meta` | 否 | 字符串 | 标题下方的副标题或元信息说明 |
+| `description` | 与 `points` 二选一 | 字符串 | 卡片主说明段落（支持行内加粗与代码） |
+| `points` | 与 `description` 二选一 | 字符串数组 | 下方带编号的要点列表 |
+| `source` | 否 | 字符串或 `{ title, url }` | 右下角出处角标 |

package/docs/handbook/components/chart.md

@@ -0,0 +1,52 @@
+---
+title: 条形图表（chart）
+navTitle: 条形图表
+description: 用 YAML 数据直接生成比例条形图，下方自带可展开的数据表格。
+section: components
+order: 35
+badge: chart
+---
+
+```garden chart
+title: 三种版面区域的宽度上限
+xLabel: 版面区域
+yLabel: 最大宽度
+unit: px
+data:
+  - x: 普通正文列
+    y: 740
+  - x: 宽幅配图区
+    y: 1040
+  - x: 多列宽表格
+    y: 1340
+caption: 点击「查看数据表」可展开完整数值表格。
+```
+
+````markdown
+```garden chart
+title: 三种版面区域的宽度上限
+xLabel: 版面区域
+yLabel: 最大宽度
+unit: px
+data:
+  - x: 普通正文列
+    y: 740
+  - x: 宽幅配图区
+    y: 1040
+  - x: 多列宽表格
+    y: 1340
+caption: 点击「查看数据表」可展开完整数值表格。
+```
+````
+
+- **用**：对比 2～8 组同量纲数值的长短比例时。
+- **别用**：已经在同一个小节里放了同组数字的 Markdown 表格时不要再画一张 `chart`（图表底部已自带可展开的数据表）。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `title` | 建议 | 字符串 | 图表标题 |
+| `data` | 是 | `{ x, y, label? }[]`（至少 2 项） | 数据行列表，`x` 为名称，`y` 为数值 |
+| `unit` | 否 | 字符串 | 数值后缀单位（当数据项未单独指定 `label` 时自动拼接） |
+| `xLabel` | 否 | 字符串 | 展开数据表第一列的表头名称（默认 `项目`） |
+| `yLabel` | 否 | 字符串 | 展开数据表第二列的表头名称（默认 `数值`） |
+| `caption` | 否 | 字符串 | 图表底部的图注说明 |

package/docs/handbook/components/compare.md

@@ -0,0 +1,40 @@
+---
+title: 并排对比（compare）
+navTitle: 并排对比
+description: 把两到三种方案左右并列，对比各自的取舍与属性。
+section: components
+order: 33
+badge: compare
+---
+
+```garden compare
+items:
+  - title: 只贴一段 diff
+    text: 读者只看到增删行；前面没有完整代码块时，garden check 报 diff-orphan 错误。
+    能否复制新版: 不能
+  - title: 完整代码 + 紧跟的 diff
+    text: 两段合成一个代码框，可在「代码」和「对比上一版」之间切换。
+    能否复制新版: 两个标签下都复制新版
+```
+
+````markdown
+```garden compare
+items:
+  - title: 只贴一段 diff
+    text: 读者只看到增删行；前面没有完整代码块时，garden check 报 diff-orphan 错误。
+    能否复制新版: 不能
+  - title: 完整代码 + 紧跟的 diff
+    text: 两段合成一个代码框，可在「代码」和「对比上一版」之间切换。
+    能否复制新版: 两个标签下都复制新版
+```
+````
+
+- **用**：并排对比 2～3 种方案、配置方式或改动前后的行为差异时（每格文字控制在 60 字以内）。
+- **别用**：对比项超过 3 个或需要横向对齐多个参数维度时，直接用 Markdown 表格。
+
+| 字段 | 必填 | 类型 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `items` | 是 | 数组（至少 2 项） | 对比项列表；每项也可简写为 `"标题：说明"` 单行字符串 |
+| `items[].title` | 建议 | 字符串 | 该对比列的标题 |
+| `items[].text` | 建议 | 字符串或字符串数组 | 该对比列的正文说明 |
+| `items[].<自定义键>` | 否 | 字符串或数字 | 除 `title` / `text` 外的附加键值会渲染在卡片底部的属性标签行 |