hd-garden 0.14.3 → 0.14.6

package/.agents/skills/garden-compose/SKILL.md

@@ -8,14 +8,14 @@ description: "将原文与一句效果或参考图，编译为 Garden Compose
 ## 短决策链：问题 → 约束 → 推荐路线 → 原文 → 验证
 1. 作者只需原文＋一句效果/参考图＋可选不要什么。分开事实、效果与修改范围；保留措辞、顺序、完整段落和资源，不补摘要、数据、因果。普通 Markdown 足够就不加组件。
 2. 选型必读 `references/visual-selection.md`。AI 内部先判断移动阅读任务（扫读/顺序/对照/空间关系），必读 `references/mobile-contract.md`，写桌面＋窄屏约束卡，再取**唯一推荐路线**；不是限定合法组件的白名单。只在事实关系、隐藏内容、阅读顺序等重大取舍不明时询问；其余按已记录默认收敛，不让作者填技术表单。
-3. 按路线只读 `references/layout-recipes.md` 对应小节；陌生组合/参考图再读 `references/rendering-model.md`。需要新组合时读 `references/composition-patterns.md`，仍先建立共享容器。frame/tone/size是正交选择，不因微调换组件家族。
+3. 原文关键数值＋标签/单位用`metric`；独立解释类别用`equal-cards`，不造数值。标题＋徽标用`row align="center" justify="between" wrap="nowrap"`：justify管主轴、align管交叉轴，标题保留内容宽；nowrap仅约束局部，长标题仍须窄屏验收。按路线只读 `references/layout-recipes.md` 对应小节；陌生组合/参考图再读 `references/rendering-model.md`。需要新组合时读 `references/composition-patterns.md`，仍先建立共享容器。frame/tone/size是正交选择，不因微调换组件家族。
 4. 作者组件只用 `garden compose`；内部静态/语义/交互能力按需读 `references/static-play.md`。语义字段、图标、允许子项以 `npx --no-install garden ui schema` 为准，按需存到 `.garden`，不预读整本目录。Markdown/安全HTML岛保存完整块内容；受限表达式不等于任意JS。
 
 ## 写入与验证
 1. 必读 `references/workflow.md`：scan，保存id/行号、完整围栏base hash与原文。首次插入意图块和已有块apply不同；未编译意图不是完成品。
-2. 按 `references/rendering-model.md` 的集中禁令与配方生成候选。正文默认继承文章动态字体/字号/行高；不缩字凑版。显式size只响应明确要求或真实层级。框读frames、颜色读colors；不要把场景框、内部边框和底色混为一谈。
+2. 先按 `references/rendering-model.md` 量宿主可用宽度与各层padding，再生成候选；不把主题/运行时挤压误诊成原文过长。正文默认继承文章动态字体/字号/行高；不缩字凑版。显式size只响应明确要求或真实层级。框读frames、颜色读colors；不要把场景框、内部边框和底色混为一谈。
 3. 属性级微调优先，但当前apply仍替换完整围栏：候选文件＋稳定id（没有才用scan行号）＋原完整base hash；冲突即重读，不绕过保护。不误伤邻块或改写intent原话。
 4. `scripts/check.mjs` 与 `garden check`保持原契约；有内部约束卡可另跑 `scripts/lint-layout.mjs`（workflow说明）。风险提示不等于语法错误；静态属性可能被丢弃，解析通过不等于生效。
-5. 所有新布局都默认承担移动端责任，不等作者指出手机问题。按mobile-contract先验最窄屏和放大正文，再在完整主题与真实CSS顺序下检查桌面、computed样式、几何及阅读密度；交互另测。分别报告：结构/解析、渲染、浏览器几何/交互、独立AI生成试验。没有对应证据就写未验证。
+5. 所有新布局都默认承担移动端责任，不等作者指出手机问题。按mobile-contract先验最窄屏和放大正文，再在完整主题与真实CSS顺序下检查桌面、computed样式、几何及阅读密度；交互另测正常首页Link进入、返回再进、后退/前进与直接链接；sandbox不能以强刷或_top代替修复。静态构建自动验导出资源，也可用 `garden verify --rendered` 重跑，但它不证明浏览器导航。分别报告：结构/解析、渲染、浏览器几何/交互、独立AI生成试验。没有对应证据就写未验证。
 
 脚本仅使用已安装本地引擎，不下载包、不默认调用模型或导出全目录。缺依赖就报告；可复用维护经验只提出候选，不在文章任务里自行改技能。

package/.agents/skills/garden-compose/references/layout-recipes.md

@@ -14,7 +14,7 @@ Use `<grid cols={3} gap={3}>` with three direct `<card>` children. `cols` accept
 
 三个直接 card 子元素配 `grid cols={3} gap={3}`；cols 为 1–6。等宽来自等分网格；当前主题在视口 ≤800px 时收为单列，不强制窄屏横排。
 
-- `gap` and `padding`: 0–4 → 0/4/8/12/16px. A restrained consistent default is `padding={3} radius="md" border="subtle" background="surface"` on each card. Apply the same tokens to every card unless a distinct style was requested. / 未指定差异样式时，为所有卡片使用同一组 token。
+- `gap` and `padding`: 0–4 → 0/4/8/12/16px. A restrained consistent default is `padding={3} radius="md" border="subtle" background="transparent"` on each card. Preserve grouping borders; do not add fill merely because items are peers. Choose explicit `background="surface"` only for intentional reading groups or requested hierarchy. / 默认透明并保留合理分组边框；内卡surface按阅读分组或明确层级需要选择，不是所有并列项都加底。
 - Supported radii: none/sm/md/lg/xl/full. Borders: true/false/subtle/none/strong. Backgrounds include surface, surface-secondary, surface-accent, surface-tip, surface-muted, paper, well, transparent. Consult tokens only when needed.
 - Equal width does not mean equal word count, forced line breaks or fixed heights. Grid items stretch within their row by normal CSS grid behavior; content remains natural, without height clamps or filler text. / 不为等宽删改原文、补字或强插换行，也不把多行内容裁成固定高度。
 - Icons and semantic colors are optional, not mandatory decoration. Do not invent icons or inject arbitrary CSS. / 图标与颜色可选，不强行装饰。
@@ -30,15 +30,15 @@ Use `<grid cols={3} gap={3}>` with three direct `<card>` children. `cols` accept
 </intent>
 <figure frame="none">
 <grid cols={3} gap={3}>
-  <card padding={3} radius="md" border="subtle" background="surface">
+  <card padding={3} radius="md" border="subtle" background="transparent">
     <title>人员</title>
     <text>解决的是团队到底需要哪几类人，各自管什么、不管什么，他们如何进行合作。</text>
   </card>
-  <card padding={3} radius="md" border="subtle" background="surface">
+  <card padding={3} radius="md" border="subtle" background="transparent">
     <title>流程</title>
     <text>从冒出一个点子到软件上线，先迈左脚还是先迈右脚，怎么用最低成本试错。</text>
   </card>
-  <card padding={3} radius="md" border="subtle" background="surface">
+  <card padding={3} radius="md" border="subtle" background="transparent">
     <title>产品</title>
     <text>一款真正的好产品本身长什么样，有哪些绝不能碰的死穴。</text>
   </card>
@@ -113,3 +113,18 @@ Use this for independent explanations, not a workflow. Derive the alignment hier
 - centered-chip：只承诺局部贴标。完整问句、长标题、双语标签和放大字体必须实测；不自动把所有正文居中。长扫描清单优先开始对齐的连续阅读，必要时用局部重点居中，不通过sm来压高度。
 - prose-list / frameless：保持真实标记、顺序、正文基线和自然段落；去掉无意义的多层场景表面不是删掉所有必要分组。
 同一树能响应式重排时使用已有机制；若需要尚未支持的断点条件对齐/拓扑，不复制两套文字隐藏一套、不发明媒体属性。采用兼容两端且保真的最小方案并注明视觉取舍；无法满足作者明确硬约束时标未完成，而非让作者做设备调参。
+
+## Source-backed metrics · 原文指标
+Use `metric` for a source-backed number plus label/unit/caption; use equal-cards for independent explanatory categories. Do not invent values or convert prose-only peers into metrics. / 原文数值＋标签/单位/说明用metric，独立解释类别用equal-cards；不造数据。
+
+## Title and badge · 标题与徽标
+Use `row align="center" justify="between" wrap="nowrap"` with a title and badge. Explicit justify controls distribution; align controls the cross axis. Between/around title leaves remain content-sized; nowrap keeps this local row, not the whole article, together. Verify long titles at the actual narrow width. / between让标题与徽标两端分布，align管交叉轴；标题保留内容宽，nowrap只约束这一局部，长标题仍须窄屏实测。
+
+## Measured DOM connectors · 可复用的实测连线
+
+- First choose native `relations/entity/edge` when its compact ring and detail interaction match the reader's task. It is not an arbitrary-position graph router. / 环形关系＋详情合适时优先原生relations，不承诺自由拓扑排版。
+- Custom topology, branch ports or exact placement: keep the same Compose fence and use an offline `sandbox`. Keep labels in ordinary HTML, inheriting its body font; SVG draws **lines only**, never a whole text diagram scaled to fit. The iframe is an isolated document: article web fonts are not automatically available. / 自定义拓扑用同一compose入口内的sandbox；文字留在DOM，SVG只画线，不缩放整张文字图。iframe不自动继承文章web字体，须如实验证。
+- Reuse `measured-connectors.js` inside the sandbox's literal JS, then call `mountMeasuredConnectors(root, [{from:'a',to:'b'}, {from:'a',to:'c',route:'elbow'}, {from:'b',to:'c',route:'elbow',dashed:true}])`. The root needs `position:relative`; node elements need unique `data-node` ids. CSS owns layout, the recipe owns measurement. No new engine component/API or network import is involved. / 根容器定位，节点唯一id；CSS布局与测量连线分工，不发明组件或远程依赖。
+- It uses ResizeObserver, font readiness and SVG screen-coordinate conversion. It returns a disposer; remount on topology changes. Supported for a stable node set: straight edges by default; `route:"elbow"` draws an axis-aligned, midpoint-bend path between measured boundary anchors; `dashed:true` adds a 6/4 dash pattern independently. All update on node/root resize, font readiness and position-only node style/class changes; dragging controls and animation are not supplied. **Not supported:** automatic obstacle avoidance, edge labels, arrowheads, dragging or automatic graph layout. Nodes must not overlap. Choose a readable non-crossing arrangement; if hard requirements need these missing behaviors, implement and test them explicitly rather than claiming this recipe supplies them. / 支持实测直线、`route:'elbow'`轴对齐中点转折与独立`dashed:true`虚线；基于真实节点框重测两端，随字体/容器重排及节点style/class移动更新；不提供自动避障、边标签、箭头、拖拽或自动排图，不能把端点测试当成完整复杂图验收。
+- Protect readable node widths before choosing a narrow layout. For spatial relationships that must retain their arrangement, wrap the graph in a labelled, keyboard-focusable local viewport (`max-width:100%; overflow-x:auto`); a two-column graph can use `min-width:34em` and natural word wrapping (`overflow-wrap:break-word; word-break:normal`). Font enlargement increases that floor, not shrinks type. Resize the viewport, not below the node floor. If the task permits reflow, explicitly reroute edges so they do not run through intervening nodes. This is recipe CSS, not a new engine API. / 空间关系需保留时用有标签、可键盘访问的局部横滚；节点保留可读最小宽，正文自然换词，不以anywhere挤成碎词、不缩字。可重排的任务另验改序与连线，不把直排后穿过中间节点当成功。
+- Verify actual endpoints, elbow segment axes and dash style after reflow and enlarged text at 300/344/375/430 and desktop widths; inspect crossings, reading order, scrollbar ownership and fullscreen separately. `tests/measured-connectors-browser.test.mjs` verifies the foundation, not every topology. / 按真实节点框验端点，另审交叉、阅读顺序、滚动归属与全屏；测试基础能力不等于所有拓扑都已验收。

package/.agents/skills/garden-compose/references/measured-connectors.js

@@ -0,0 +1,94 @@
+// Offline sandbox recipe, not a Compose component or an automatic graph router.
+// root: positioned DOM container; nodes: unique data-node ids.
+// edges: {from,to,route?:"straight"|"elbow",dashed?:boolean}; no obstacle router.
+function mountMeasuredConnectors(root, edges) {
+  const namespace = 'http://www.w3.org/2000/svg';
+  const nodes = new Map([...root.querySelectorAll('[data-node]')].map(node => [node.dataset.node, node]));
+  if (nodes.size !== root.querySelectorAll('[data-node]').length) throw new Error('Duplicate connector node id');
+  for (const edge of edges) {
+    if (!nodes.has(edge.from) || !nodes.has(edge.to)) throw new Error('Unknown connector node id');
+    if (edge.route !== undefined && !['straight', 'elbow'].includes(edge.route)) throw new Error('Unknown connector route');
+    if (edge.dashed !== undefined && typeof edge.dashed !== 'boolean') throw new Error('Connector dashed must be boolean');
+  }
+  const svg = document.createElementNS(namespace, 'svg');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.classList.add('connector-lines');
+  Object.assign(svg.style, { position: 'absolute', inset: '0', width: '100%', height: '100%', overflow: 'visible', pointerEvents: 'none' });
+  const paths = edges.map(edge => {
+    const line = document.createElementNS(namespace, 'path');
+    line.dataset.from = edge.from;
+    line.dataset.to = edge.to;
+    line.dataset.route = edge.route ?? 'straight';
+    if (edge.dashed) line.setAttribute('stroke-dasharray', '6 4');
+    line.setAttribute('fill', 'none');
+    line.setAttribute('stroke', 'currentColor');
+    line.setAttribute('stroke-width', '1.5');
+    svg.append(line);
+    return line;
+  });
+  root.prepend(svg);
+  let active = true;
+  let scheduled = 0;
+  function draw() {
+    scheduled = 0;
+    if (!active || !svg.isConnected) return;
+    const matrix = svg.getScreenCTM();
+    if (!matrix) return;
+    const inverse = matrix.inverse();
+    for (const [index, edge] of edges.entries()) {
+      const from = nodes.get(edge.from).getBoundingClientRect();
+      const to = nodes.get(edge.to).getBoundingClientRect();
+      const a = { x: from.x + from.width / 2, y: from.y + from.height / 2 };
+      const b = { x: to.x + to.width / 2, y: to.y + to.height / 2 };
+      // Prefer a genuinely separated axis: tall peer cards can overlap vertically.
+      // A center-only choice could send the first elbow segment back into its node.
+      const separatedX = from.right <= to.left || to.right <= from.left;
+      const separatedY = from.bottom <= to.top || to.bottom <= from.top;
+      const horizontal = separatedX !== separatedY ? separatedX : Math.abs(b.x - a.x) > Math.abs(b.y - a.y);
+      if (horizontal) {
+        const forward = b.x > a.x;
+        a.x = forward ? from.right : from.left;
+        b.x = forward ? to.left : to.right;
+      } else {
+        const forward = b.y > a.y;
+        a.y = forward ? from.bottom : from.top;
+        b.y = forward ? to.top : to.bottom;
+      }
+      const start = new DOMPoint(a.x, a.y).matrixTransform(inverse);
+      const end = new DOMPoint(b.x, b.y).matrixTransform(inverse);
+      const points = [start];
+      if (edge.route === 'elbow') {
+        // Mid-gap orthogonal route, recalculated from actual node bounds.
+        // Intentionally no obstacle search or automatic node placement.
+        if (horizontal) {
+          const x = (start.x + end.x) / 2;
+          points.push({ x, y: start.y }, { x, y: end.y });
+        } else {
+          const y = (start.y + end.y) / 2;
+          points.push({ x: start.x, y }, { x: end.x, y });
+        }
+      }
+      points.push(end);
+      paths[index].setAttribute('d', points.map((point, i) => `${i ? 'L' : 'M'}${point.x},${point.y}`).join(' '));
+    }
+  }
+  function schedule() { if (active && !scheduled) scheduled = requestAnimationFrame(draw); }
+  const observer = new ResizeObserver(schedule);
+  observer.observe(root);
+  for (const node of nodes.values()) observer.observe(node);
+  const changes = new MutationObserver(schedule);
+  // Position-only style/class changes do not trigger ResizeObserver.
+  // Do not observe path `d` writes: measurement must not reschedule itself.
+  changes.observe(root, { attributes: true, attributeFilter: ['style', 'class'], subtree: true });
+  window.addEventListener('resize', schedule);
+  document.fonts?.ready.then(schedule);
+  schedule();
+  return () => {
+    active = false;
+    cancelAnimationFrame(scheduled);
+    observer.disconnect();
+    changes.disconnect();
+    window.removeEventListener('resize', schedule);
+    svg.remove();
+  };
+}

package/.agents/skills/garden-compose/references/rendering-model.md

@@ -6,14 +6,19 @@
 - 关系决定共同容器：一个图标对应的标题与所有正文要属于一个重复单元；标题和正文必须同在右侧容器。分隔整条目时 divider 放两条 row 之间，而非右栏内。
 - row 默认 wrap/stretch、8px gap；直接 card/stack/title/text 共分可用宽度，icon 固定不缩。窄屏默认会改行流；需要持续图标栏用 wrap="nowrap" 并测试不溢出。
 - row > stack 有 **12px 顶部 padding**；不能假定任意嵌套同样表现。group 为 width:100%、min-width:0 的纵向容器，能在固定 icon 旁收缩，支持 gap，避开该上下文顶距。prose 不能凭空赋予未实现的 gap 行为。
-- align="center" 可能同时触发容器对齐与 text-align，并向子孙继承。当前 title/text 的显式 align="start" 会保留并输出 data-align。用一个共享 group 和显式开始对齐，不要把 title 独立成横向等分栏、正文又放回全宽。
+- row 的 align 管交叉轴，justify 管主轴；显式 justify 始终优先，不被 align="center" 或徽标的默认居中覆盖。文字仍可能继承 text-align。当前 title/text 的显式 align="start" 会保留并输出 data-align。用一个共享 group 和显式开始对齐，不要把 title 独立成横向等分栏、正文又放回全宽。
 - icon 名查 schema/icons 实际目录；不存在报错。SVG width 属性不等于最终像素：当前 CSS sm13、md15、lg18、xl22px，小卡上下文另有覆盖，必须测 computed/rect。
 - 多段正文分别放 text，或用 markdown/html 岛保存真实 p。text 内空行是 inline break，不是独立段落。图标签有截断/行钳制时不能塞完整正文去丢字。
 
+## Diagnose the host before rewriting content · 先诊断宿主
+Measure viewport → `.article-reading-column` → `.garden-ui-body` → iframe; record each width and computed padding. Do not infer content width from a desktop breakpoint. The reading track takes priority over side rails; a frameless runtime has no body inset; fullscreen controls occupy a top band outside the frame. Post mobile TOC entries are in normal flow before the article. / 依次量视口、正文栏、运行时正文与iframe，不先删字或缩字。侧栏让位正文，frame="none"不再叠运行时内距，全屏按钮占外部顶栏，手机目录入口在正文前正常排版。
+
+For a title and trailing badge, use `<row align="center" justify="between" wrap="nowrap"><title align="start">…</title><badge>…</badge></row>`. Its text/title children are content-sized and may shrink/wrap naturally, not width:100% columns. Explicit fills, scene framing and fullscreen are independent choices. / 标题＋尾部徽标直接组合已有属性；不靠换组件、固定标题宽度或缩字绕开。
+
 ## 集中禁令与风险分级
 - **必选结构（已选icon-rail）**：icon和一个group同属row，标题与全部正文/列表同属group；分隔线在row之间。不要正文逃出右栏，不用row>stack替代group来碰运气。
 - **无效属性**：stack不因direction="row"变横向；用真实row。未知静态属性可能归一化丢失，当前lint不能从归一化树找回它们；对照源属性与schema，缺少未知属性诊断是引擎需求，不谎称已机器覆盖。
-- **风险而非全局错误**：row>stack的12px顶距、居中row直接title/text的flex:1、center同时改变主轴/交叉轴/文字、nowrap长链、显式size和叠框。这些在其他语境可能有意，必须结合内部约束卡判断，不能一律禁用。
+- **风险而非全局错误**：row>stack的12px顶距、居中row直接title/text的flex:1、center仍可能向后代继承文字居中（但不覆盖显式justify）、nowrap长链、显式size和叠框。这些在其他语境可能有意，必须结合内部约束卡判断，不能一律禁用。
 - **箭头看实际绘制方向**：right是源意图，不必等于当前屏幕方向。真实SVG默认向下；桌面旋转为right，≤800px取消旋转配合默认row转column。先看computed transform/屏幕向量，不把data-dir当几何证据。nowrap让row保持横向却不自动保留箭头旋转，须专项检查。
 - **必须浏览器**：icon glyph光学齐平不是节点矩形相等；内容宽居中、完整主题字号/列表间距、溢出与手机回退不能从AST推断。用computed与rect及截图分别取证。
 
@@ -50,7 +55,7 @@ The authoritative, demand-loaded catalog is `npx garden ui schema`: actual seman
 
 First identify what belongs together. A heading and all its paragraphs must share a container. Next choose columns and proportions, then alignments and typography. Only then add surfaces and decorative details.
 
-A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` on a row changes more than vertical placement: theme rules also center text. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
+A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` controls the cross axis and can inherit centered text; an explicit `justify` independently controls the main axis and takes precedence over default badge centering. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
 
 Direct `row > stack` has 12px top padding in the current theme. A `group` is a width:100%, min-width:0 vertical container that shrinks beside the fixed icon and reads gap without that contextual padding; use it when icon and heading must begin on the same top line. Explicit `align="start"` survives normalization and emits data-align.
 
@@ -118,6 +123,8 @@ Use `markdown` or `html` islands for full paragraphs, lists, headings, blockquot
 
 Safe HTML supports allowlisted local `style` properties, including useful layout and typography; inspect the generated schema for the actual set. Unsupported tags/properties, events, unsafe URLs, executable scripts and network CSS functions report diagnostics. Do not expand the article allowlist into arbitrary execution. An intentional executable demo uses `sandbox` inside the **same Compose entry**, with literal html/css/js and no parent origin access. Sandbox layout is its own document, not inherited article prose.
 
+For measured node connections, load layout-recipes.md and measured-connectors.js: straight, midpoint orthogonal elbow and optional dashed edges follow real DOM bounds. This is a sandbox recipe, not automatic graph layout or obstacle avoidance.
+
 ## Verification levels
 
 1. Run `npx garden ui check <file>` (and `npx garden check <file>` for real file paths). Preserve original text/resources and inspect diagnostics.

package/.agents/skills/garden-compose/references/visual-selection.md

@@ -14,6 +14,7 @@ Load when choosing how to explain source content, not for every repair. Use the
 | 图标窄栏、标题正文共左缘 | icon-rail：stack重复row(icon＋group)，divider在row间 | 不把正文放row外；不当流程 |
 | 短阶段从左到右 | flow-row：row＋真实顺序箭头；窄屏/长内容回退flow-stack | 不靠缩字/nowrap强撑手机 |
 | 长阶段或纵向顺序 | flow-stack：stack＋下箭头 | 无顺序的条目不加箭头 |
+| 原文关键数值＋标签/单位 | metric：保留原始值、单位与说明 | 不造数据；无数值的解释类别仍用equal-cards |
 | 并列等宽卡片 | equal-cards：grid＋直接card | 非真实共同维度不走compare |
 | 图标贴标题，两者一起居中 | centered-chip：内容宽标题壳＋内部图标标题行，下方正文独立 | 不只给全宽row设center；候选须浏览器验收 |
 | 跟正文一样的列表 | prose-list：普通Markdown；场景内用markdown岛 | 不写假圆点；不为列表手感换到compare |

package/.agents/skills/garden-compose/references/workflow.md

@@ -44,3 +44,10 @@ node .agents/skills/garden-compose/scripts/lint-layout.mjs content/posts/post.md
 ## Mobile acceptance · AI内部，不要求作者补规格
 几何卡补可选`"mobile":{"readingMode":"sequence","reflow":true}`；readingMode可选sequence/scan-list/comparison/spatial，reflow为布尔。lint只在显式reflow的flow-row中拒绝场景顶层流向row的nowrap（不误禁内部贴标row）；icon-rail局部nowrap不被误禁。scan-list的成组居中只给风险提示，不凭AST断言过高或难读。
 浏览器验证遵守mobile-contract：记录实际CSS viewport、内容宽、正常/放大正文、每层滚动与实际箭头向量，并人工审查整组阅读节奏。保留首稿和源hash，失败后的修订单独编号，不能把修后结果算首轮成功。默认check参数/退出状态不变，mobile字段不是runtime DIL属性。
+
+## Built artifact gate · 最终产物门
+`STATIC_EXPORT=1 garden build` now checks the final export automatically. `garden verify --rendered` reruns it without rebuilding: actual HTML stylesheet/script links, literal JS imports (including lazy chunks), Compose/runtime CSS and per-page client navigation payloads. Missing assets or corrupt payloads fail. / 静态构建后自动检查真实HTML/CSS/JS依赖及导航payload，缺失即失败；不是只看源代码导入。
+
+This is asset integrity, **not** visual or lifecycle acceptance. Complete-theme browser tests and the real site's normal Link → article → home → re-entry → history/direct sequence remain separate gates. Record iframe height messages from its own contentWindow, srcdoc length and computed geometry; a populated srcdoc alone does not prove execution. Do not claim navigation fixed from a direct-link pass. / 资源完整≠样式生效≠生命周期通过；iframe需记录实际消息、srcdoc与几何，不能凭直接链接成功宣称客户端导航已修好。
+
+Measured connector recipes: verify boundary endpoints after enlarged labels and container resize; for elbow edges also verify every segment is axis-aligned, and dashed edges retain their dash style. Do not infer obstacle avoidance from endpoint tests. / 连线需验实测端点、肘线各段轴对齐与虚线样式；另审交叉，不能据此宣称自动避障。

package/app/components/PostReadingView.tsx

@@ -110,6 +110,7 @@ export function PostReadingView({
           ) : null}
         </header>
         <div className="article-reading-layout">
+          <TableOfContents headings={headings} />
           <div className="article-reading-column">
             <ArticleMeasure />
             <div className="e-content">
@@ -125,7 +126,6 @@ export function PostReadingView({
             />
             <Comments slug={commentsSlug} />
           </div>
-          <TableOfContents headings={headings} />
         </div>
       </article>
     </main>

package/app/components/SiteHeader.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+import { TOC_PANEL_ID, TOC_CONTROL_ID, TOC_CLOSED_ID } from "../lib/reading-navigation";
+
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import {
@@ -316,6 +318,7 @@ export function SiteHeader() {
     <>
       {/* Targets for the no-JavaScript menu links below. Fixed and outside the sticky header, so
           following #sh-menu-on or #sh-menu-off never scrolls the page (the TOC drawer works the same way). */}
+      <span className="sh-menu-target" id={TOC_CLOSED_ID} aria-hidden="true" />
       <span className="sh-menu-target" id="sh-menu-on" aria-hidden="true" />
       <span className="sh-menu-target" id="sh-menu-off" aria-hidden="true" />
       <header className="sh-header" id="site-header">
@@ -333,6 +336,11 @@ export function SiteHeader() {
             ))}
           </nav>
           <div className="sh-tools">
+            <span id={TOC_CONTROL_ID} className="sh-reading-control">
+              <a className="toc-header-nojs" href={`#${TOC_PANEL_ID}`} aria-label={t.toc}>
+                {t.tocShort}
+              </a>
+            </span>
             <button ref={searchTriggerRef} className="sh-search" type="button" onClick={openSearch} onPointerEnter={prefetchSearch} onFocus={prefetchSearch} aria-label={t.searchArticles} aria-expanded={searchOpen} aria-controls="site-search-dialog">
               <svg viewBox="0 0 20 20" aria-hidden="true">
                 <circle cx="9" cy="9" r="5.8" />

package/app/components/TableOfContents.tsx

@@ -6,10 +6,13 @@ import {
   useId,
   useRef,
   useState,
+  useSyncExternalStore,
   type MouseEvent,
   type ReactNode,
 } from "react";
-import { List, X } from "@phosphor-icons/react";
+import { createPortal } from "react-dom";
+import { TOC_PANEL_ID, TOC_CONTROL_ID, TOC_CLOSED_ID } from "../lib/reading-navigation";
+import { X } from "@phosphor-icons/react";
 import { ui, type UiLang } from "../lib/i18n";
 
 type Heading = { depth: number; text: string; id: string; no?: string };
@@ -114,6 +117,20 @@ const scrollToHeading = (id: string) => {
   html.style.scrollBehavior = previousBehavior;
 };
 
+// The server-rendered header owns the slot; this component owns one drawer/control.
+// Observe slot replacement during client navigation, never poll or duplicate the TOC.
+const readControlHost = () => document.getElementById(TOC_CONTROL_ID);
+const serverControlHost = () => null;
+function subscribeControlHost(changed: () => void) {
+  let host = readControlHost();
+  const observer = new MutationObserver(() => {
+    const next = readControlHost();
+    if (next !== host) { host = next; changed(); }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+  return () => observer.disconnect();
+}
+
 export function TableOfContents({
   headings,
   label,
@@ -131,9 +148,11 @@ export function TableOfContents({
     () => new Set(),
   );
   const [mobileOpen, setMobileOpen] = useState(false);
-  const panelId = useId();
+  const panelId = TOC_PANEL_ID;
+  const controlHost = useSyncExternalStore(subscribeControlHost, readControlHost, serverControlHost);
   const listId = useId();
   const listRef = useRef<HTMLOListElement>(null);
+  const panelRef = useRef<HTMLElement>(null);
   const mobileTriggerRef = useRef<HTMLButtonElement>(null);
   const mobileCloseRef = useRef<HTMLButtonElement>(null);
   const restoreMobileTriggerFocusRef = useRef(false);
@@ -283,7 +302,22 @@ export function TableOfContents({
       mobileCloseRef.current?.focus({ preventScroll: true });
     });
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") closeMobileToc(true);
+      if (event.key === "Escape") {
+        event.preventDefault();
+        closeMobileToc(true);
+      }
+      if (event.key !== "Tab") return;
+      const controls = Array.from(panelRef.current?.querySelectorAll<HTMLElement>("a[href], button:not([disabled])") ?? [])
+        .filter((control) => control.getClientRects().length > 0 && getComputedStyle(control).visibility !== "hidden");
+      const first = controls[0];
+      const last = controls.at(-1);
+      if (event.shiftKey && document.activeElement === first && last) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last && first) {
+        event.preventDefault();
+        first.focus();
+      }
     };
     const handleViewportChange = () => {
       if (!mobileQuery.matches) setMobileOpen(false);
@@ -346,6 +380,13 @@ export function TableOfContents({
     setActiveId(id);
     closeMobileToc();
     trackAnchorLayout(id);
+    const heading = document.getElementById(id);
+    if (heading) {
+      const temporaryTabIndex = !heading.hasAttribute("tabindex");
+      if (temporaryTabIndex) heading.tabIndex = -1;
+      heading.focus({ preventScroll: true });
+      if (temporaryTabIndex) heading.addEventListener("blur", () => heading.removeAttribute("tabindex"), { once: true });
+    }
   };
 
   const renderNode = (node: TocNode, path: number[]): ReactNode => {
@@ -395,7 +436,7 @@ export function TableOfContents({
 
   return (
     <>
-      <button
+      {controlHost ? createPortal(<button
         ref={mobileTriggerRef}
         className="toc-mobile-trigger"
         type="button"
@@ -406,16 +447,8 @@ export function TableOfContents({
         data-mobile-open={mobileOpen}
         onClick={() => setMobileOpen(true)}
       >
-        <List size={17} weight="bold" aria-hidden="true" />
-        <span>{t.tocShort}</span>
-      </button>
-      {/* Without JavaScript the button above does nothing. This link opens the
-          drawer through :target instead; CSS shows it only when scripting is
-          off, so with JavaScript nothing here is visible. */}
-      <a className="toc-nojs-trigger" id={`${panelId}-open`} href={`#${panelId}`} aria-label={`${t.open}${label}`}>
-        <List size={17} weight="bold" aria-hidden="true" />
         <span>{t.tocShort}</span>
-      </a>
+      </button>, controlHost) : null}
       <button
         className="toc-mobile-backdrop"
         type="button"
@@ -425,6 +458,9 @@ export function TableOfContents({
         onClick={() => closeMobileToc(true)}
       />
       <aside
+        ref={panelRef}
+        role={mobileOpen ? "dialog" : undefined}
+        aria-modal={mobileOpen ? true : undefined}
         className="toc toc-rail"
         id={panelId}
         aria-label={label}
@@ -441,7 +477,7 @@ export function TableOfContents({
           >
             <X size={18} aria-hidden="true" />
           </button>
-          <a className="toc-nojs-close" href={`#${panelId}-open`} aria-label={`${t.close}${label}`}>
+          <a className="toc-nojs-close" href={`#${TOC_CLOSED_ID}`} aria-label={`${t.close}${label}`}>
             <X size={18} aria-hidden="true" />
           </a>
         </div>

package/app/globals.css

@@ -3917,62 +3917,10 @@ html[data-theme="dark"] .search-footer {
     overflow: visible;
   }
 
-  .toc-mobile-trigger,
-  .toc-nojs-trigger {
-    position: fixed;
-    right: calc(16px + env(safe-area-inset-right));
-    bottom: calc(16px + env(safe-area-inset-bottom));
-    z-index: 70;
-    min-height: 44px;
-    padding: 0 18px 0 15px;
-    display: inline-flex;
-    align-items: center;
-    gap: 8px;
-    border: 1px solid #d9d5cc;
-    border-radius: 999px;
-    background: rgb(255 255 255 / 94%);
-    box-shadow: 0 2px 10px rgb(27 26 24 / 10%);
-    color: var(--ink);
-    font: 600 14px/1 var(--sans);
-    letter-spacing: 0;
-    touch-action: manipulation;
-    cursor: pointer;
-    transition: opacity 160ms ease, transform 160ms ease, visibility 0s;
-  }
-
-  /* The floating contents button sits over the bottom 76px of the screen:
-     keep that much room after the last line, and keep anchors clear of it. */
-  html:has(.toc-mobile-trigger) {
-    scroll-padding-bottom: calc(76px + env(safe-area-inset-bottom));
-  }
-
-  body:has(.toc-mobile-trigger) main {
-    padding-bottom: calc(76px + env(safe-area-inset-bottom));
-  }
-
-  :root[data-theme="dark"] .toc-mobile-trigger,
-  html[data-theme="dark"] .toc-mobile-trigger,
-  :root[data-theme="dark"] .toc-nojs-trigger,
-  html[data-theme="dark"] .toc-nojs-trigger {
-    background: rgb(30 29 26 / 94%);
-    border-color: var(--rule-strong);
-    color: var(--ink);
-  }
-
-  .toc-mobile-trigger:hover,
-  .toc-mobile-trigger:focus-visible,
-  .toc-nojs-trigger:hover,
-  .toc-nojs-trigger:focus-visible {
-    transform: translateY(-2px);
-  }
-
   .toc-mobile-trigger:focus-visible,
+  .toc-header-nojs:focus-visible,
   .toc-mobile-close:focus-visible,
-  .toc-nojs-trigger:focus-visible,
-  .toc-nojs-close:focus-visible {
-    outline: 2px solid var(--accent);
-    outline-offset: 3px;
-  }
+  .toc-nojs-close:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
 
   .toc-mobile-trigger[data-mobile-open="true"] {
     opacity: 0;
@@ -4054,8 +4002,8 @@ html[data-theme="dark"] .search-footer {
 
   .toc-mobile-close,
   .toc-nojs-close {
-    width: 34px;
-    height: 34px;
+    width: 44px;
+    height: 44px;
     padding: 0;
     display: grid;
     place-items: center;
@@ -4088,9 +4036,13 @@ html[data-theme="dark"] .search-footer {
      padding on post pages but not on column pages. */
   .toc .toc-header,
   .toc .toc-list {
-    padding-inline: 20px;
+    padding-left: max(20px, env(safe-area-inset-left));
+    padding-right: max(20px, env(safe-area-inset-right));
   }
 
+  .toc .toc-item-row > a { display: flex; align-items: center; min-height: 44px; padding-block: 8px; }
+  .toc .toc-section-toggle { min-width: 44px; min-height: 44px; }
+
   .toc li {
     margin: 10px 0;
     font-size: 13px;
@@ -5707,12 +5659,6 @@ html[data-theme="dark"] .search-footer {
     display: none;
   }
 
-  .toc-nojs-trigger {
-    display: inline-flex;
-    color: var(--ink);
-    text-decoration: none;
-  }
-
   .toc-nojs-close {
     display: grid;
     text-decoration: none;
@@ -5725,7 +5671,7 @@ html[data-theme="dark"] .search-footer {
     transition: opacity 180ms ease, visibility 0s;
   }
 
-  body:has(.toc:target) .toc-nojs-trigger {
+  body:has(.toc:target) .toc-header-nojs {
     opacity: 0;
     visibility: hidden;
     pointer-events: none;

package/app/lib/i18n.ts

@@ -319,7 +319,7 @@ const en: typeof zh = {
   columnFallbackDesc: "A series of posts in reading order.",
   columnNewestFirst: (title: string | undefined) => `${title}, newest first`,
   toc: "Contents",
-  tocShort: "Contents",
+  tocShort: "TOC",
   tocPage: "On this page",
   open: "Open ",
   close: "Close ",

package/app/lib/reading-navigation.ts

@@ -0,0 +1,4 @@
+// One primary reading navigation per page; shared by the server header and client drawer.
+export const TOC_PANEL_ID = "reading-contents";
+export const TOC_CONTROL_ID = "reading-contents-control";
+export const TOC_CLOSED_ID = "reading-contents-closed";

package/app/styles/a2.css

@@ -274,7 +274,7 @@ body {
   --rail: 200px;
   --gap: 72px;
   display: grid;
-  grid-template-columns: minmax(0, var(--rail)) minmax(0, var(--col)) var(--rail);
+  grid-template-columns: minmax(0, 1fr) minmax(0, var(--col)) minmax(0, 1fr);
   column-gap: var(--gap);
   justify-content: center;
   align-items: start;
@@ -300,6 +300,8 @@ body {
 }
 
 .post-reading-page .article-reading-layout > .toc {
+  min-width: 0;
+  overflow-wrap: anywhere;
   grid-column: 3;
   grid-row: 1;
   margin-top: 0;
@@ -1582,6 +1584,9 @@ html[data-theme="dark"] .g-quiz-out.ok { color: #8fd1a0; }
 html[data-theme="dark"] .g-quiz-out.no { color: #f29aab; }
 .g-quiz-ex { margin-top: 8px; font-size: 15px; color: var(--soft); }
 .g-play { border: 1px solid var(--rule); border-radius: var(--r); padding: 14px 16px; margin: 24px 0; background: transparent; }
+/* Fullscreen controls own a top band, not a second frame or a narrow text rail. */
+.ux-fs > .ux-fsbar + .g-play { padding: 44px 0 0; border: 0; }
+.g-play > .garden-ui { margin: 0; }
 .g-play-f { margin: 0 0 10px; font-size: 14px; color: var(--soft); }
 .g-range { display: grid; grid-template-columns: 110px minmax(0, 1fr) 64px; gap: 12px; align-items: center; font-size: 14px; color: var(--muted); margin: 6px 0; }
 .g-range input { width: 100%; accent-color: var(--blue); min-height: 32px; }
@@ -2782,3 +2787,11 @@ html[data-theme="dark"] .ref-demo { --rd-s: #262624; --rd-p: #1f1e1d; --rd-i: #e
     display: none;
   }
 }
+
+/* Desktop rail spacing must not replace the mobile drawer's home-indicator inset. */
+@media (max-width: 900px) {
+  .post-reading-page .article-reading-layout > .toc,
+  .garden-doc-page > .toc {
+    padding: 0 0 calc(18px + env(safe-area-inset-bottom));
+  }
+}

package/app/styles/shell.css

@@ -36,15 +36,15 @@ img,svg{max-width:100%}
 /* ---------- header ---------- */
 .sh-header{position:sticky;top:0;z-index:40;background:var(--paper);border-bottom:1px solid transparent;transition:border-color .2s ease}
 .sh-header.is-scrolled{border-bottom-color:var(--rule)}
-.sh-bar{max-width:var(--shell);margin:0 auto;height:var(--hdr);padding:0 32px;display:flex;align-items:center;gap:28px}
-.sh-word{display:inline-flex;align-items:center;gap:10px;font:600 var(--fs-lead)/1 var(--serif);color:var(--ink);text-decoration:none;white-space:nowrap;padding:8px 0}
+.sh-bar{max-width:var(--shell);margin:0 auto;min-height:var(--hdr);height:auto;padding:0 32px;display:flex;align-items:center;gap:28px}
+.sh-word{display:inline-flex;align-items:center;gap:10px;font:600 var(--fs-lead)/1 var(--serif);color:var(--ink);text-decoration:none;white-space:normal;overflow-wrap:anywhere;min-width:0;flex:0 1 auto;line-height:1.2;padding:8px 0}
 .sh-mark{display:inline-flex;flex:none}
 .sh-mark svg{display:block;height:26px;width:auto}
-.sh-nav{display:flex;gap:4px;margin-left:auto}
+.sh-nav{display:flex;flex-shrink:0;gap:4px;margin-left:auto}
 .sh-nav a{font-size:15px;color:var(--soft);text-decoration:none;padding:8px 12px;border-radius:var(--r);transition:color .15s ease,background-color .15s ease}
 .sh-nav a:hover{color:var(--ink);background:var(--tint)}
 .sh-nav a[aria-current="page"],.sh-nav a[aria-current="true"]{color:var(--blue);font-weight:600}
-.sh-tools{display:flex;align-items:center;gap:8px}
+.sh-tools{display:flex;flex-shrink:0;align-items:center;gap:8px}
 /* A hairline box so the entry reads as a field, not a stray word. */
 .sh-search{display:inline-flex;align-items:center;gap:6px;box-sizing:border-box;height:34px;padding:0 10px 0 12px;border:1px solid var(--rule);background:transparent;color:var(--soft);border-radius:8px;font:400 15px/1 var(--sans);cursor:pointer;appearance:none;transition:color .15s ease,border-color .15s ease}
 .sh-search:hover{color:var(--ink);border-color:var(--rule-strong)}
@@ -456,3 +456,26 @@ a.sh-lang:focus-visible{outline:2px solid var(--blue);outline-offset:2px}
   --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"PingFang SC","Hiragino Sans GB","Noto Sans SC","Noto Sans CJK SC","Microsoft YaHei",system-ui,sans-serif;
   --serif:"Source Serif 4",Georgia,"Times New Roman","Source Han Serif SC","Noto Serif SC","Noto Serif CJK SC","Songti SC","STSong",serif;
 }
+
+/* Reading navigation lives in the existing sticky header, never over prose.
+   The server fallback works without JS; hydration portals the stateful control
+   into the same reserved slot. No duplicate article-start button or extra band. */
+.sh-reading-control { display: none; }
+.toc-header-nojs { display: none; }
+@media (max-width: 900px) {
+  body:has(.toc-rail) .sh-reading-control { display: inline-flex; flex: 0 0 44px; min-width: 44px; min-height: 44px; align-items: center; justify-content: center; }
+  .sh-reading-control .toc-mobile-trigger,
+  .sh-reading-control .toc-header-nojs {
+    position: static; display: inline-flex; width: 44px; min-width: 44px; height: 44px; margin: 0; padding: 0;
+    align-items: center; justify-content: center; border: 0; border-radius: var(--r);
+    background: transparent; box-shadow: none; color: var(--ink); font: 600 13px/1 var(--sans); text-decoration: none;
+  }
+  .sh-reading-control .toc-header-nojs { display: none; }
+  .sh-reading-control .toc-mobile-trigger:hover,
+  .sh-reading-control .toc-mobile-trigger:focus-visible { transform: none; background: var(--tint); }
+  .sh-reading-control .toc-mobile-trigger[data-mobile-open="true"] { visibility: visible; opacity: 1; pointer-events: none; transform: none; }
+  .sh-bar { padding-left: max(20px, env(safe-area-inset-left)); padding-right: max(12px, env(safe-area-inset-right)); }
+}
+@media (max-width: 900px) and (scripting: none) {
+  .sh-reading-control .toc-header-nojs { display: inline-flex; }
+}