dsh-ppt-studio 1.1.5 → 1.2.1

package/docs/17-/346/211/213/347/224/27313/351/241/265/350/255/246/345/221/212/351/200/220/346/235/241/345/244/204/347/275/256.md

@@ -0,0 +1,102 @@
+# 手画 13 页警告逐条处置（实测生成）
+
+> 数据来自 `verifyDeck` 实测（2026-09-29T16:35:47.179Z）；总计 **47 条**，门禁错误 **0 条** ✓。
+> 生成脚本方式：解析 `examples/hand-drawn` → `renderDeck` → 逐页 `verifyDeck` → 汇总（可复跑）。
+
+## 1. 按 code 汇总与处置
+
+| code | 条数 | 处置 |
+|---|---|---|
+| `line-diagonal-segment` | 10 | **待评估** ✗ |
+| `hotspot` | 9 | **建议级** —— 密集区评审提示，非缺陷 ✓ |
+| `density` | 7 | **建议级** —— 元素密度提示，非缺陷 ✓ |
+| `line-end-off-edge` | 7 | **待评估** ✗ |
+| `arrow-tip-inside-shape` | 5 | **待用户定 A/B** —— 读图确认为"箭头贴边 + 头部长度容差"，视觉正常 ✓；A=加 roleReason 声明（推荐）／B=端点外移（箭头将不再接上 ✗） |
+| `attach-override` | 5 | **保留（信息性）** —— attach 覆盖了手写坐标；这是引擎在**按真实边缘纠偏**，正是我们想要的 ✓ |
+| `arrow-end-short-run` | 3 | **已修** —— 04 页卡距 28→40px 后归零 ✓ |
+| `line-crossing` | 1 | **待评估** ✗ |
+
+## 2. 逐条清单
+
+| # | 页 | code | 元素 | 摘要 |
+|---|---|---|---|---|
+| 1 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,1)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 2 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (1,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 3 | 01 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 4 | 02 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 5 | 03 | `line-end-off-edge` | — | ml0 的端点离 "md0" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 6 | 03 | `line-end-off-edge` | — | ml2 的端点离 "md2" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 7 | 03 | `line-end-off-edge` | — | ml4 的端点离 "md4" 还有约 4px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 8 | 03 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 9 | 03 | `density` | page | 页面含 14 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 10 | 04 | `arrow-tip-inside-shape` | — | a0 的箭头端点落在 "lb3" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 11 | 04 | `arrow-tip-inside-shape` | — | a1 的箭头端点落在 "lb1" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 12 | 04 | `arrow-tip-inside-shape` | — | a2 的箭头端点落在 "lb2" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 13 | 04 | `arrow-tip-inside-shape` | — | a3 的箭头端点落在 "lb3" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 14 | 04 | `arrow-tip-inside-shape` | — | a4 的箭头端点落在 "lb0" **内部**（插进图形里）—— 接在图形边缘更清楚；若确实要插进去（强调/贯穿），给这条线加 `roleReason` 声明即可不再提示 |
+| 15 | 04 | `hotspot` | density | 密集区（6 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 16 | 04 | `density` | page | 页面含 12 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 17 | 05 | `hotspot` | density | 密集区（7 个元素）位于网格 (1,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 18 | 05 | `hotspot` | density | 密集区（7 个元素）位于网格 (4,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 19 | 05 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 20 | 06 | `line-diagonal-segment` | — | c0: 折线第 1 段是斜段（Δx=102 Δy=39）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleR |
+| 21 | 06 | `line-diagonal-segment` | — | c1: 折线第 1 段是斜段（Δx=59 Δy=96）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 22 | 06 | `line-diagonal-segment` | — | c3: 折线第 1 段是斜段（Δx=59 Δy=96）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 23 | 06 | `line-diagonal-segment` | — | c4: 折线第 1 段是斜段（Δx=102 Δy=39）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleR |
+| 24 | 08 | `line-diagonal-segment` | — | c0: 折线第 1 段是斜段（Δx=41 Δy=10）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 25 | 08 | `line-diagonal-segment` | — | c1: 折线第 1 段是斜段（Δx=30 Δy=69）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 26 | 08 | `line-diagonal-segment` | — | c2: 折线第 1 段是斜段（Δx=70 Δy=45）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 27 | 08 | `line-diagonal-segment` | — | c4: 折线第 1 段是斜段（Δx=70 Δy=45）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 28 | 08 | `line-diagonal-segment` | — | c5: 折线第 1 段是斜段（Δx=30 Δy=69）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 29 | 08 | `line-diagonal-segment` | — | c6: 折线第 1 段是斜段（Δx=41 Δy=10）—— 连接线请只用轴对齐段（横/竖），斜段会让箭头方向不确定；若这是刻意的环形/放射/漏斗等图形，给该元素加 role: decoration 或写 roleRe |
+| 30 | 09 | `line-crossing` | — | life2 与 m3 在 (565, 345) **交叉**（+ 型：两条都穿过对方）—— 给其中一条换车道/换进出边（或调换路由顺序）后重跑本门禁；若刻意交叉示意汇流，给该线加 roleReason 声明即静默 |
+| 31 | 09 | `line-end-off-edge` | — | life0 的端点离 "ht0" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 32 | 09 | `line-end-off-edge` | — | life1 的端点离 "ht1" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 33 | 09 | `line-end-off-edge` | — | life2 的端点离 "ht2" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 34 | 09 | `line-end-off-edge` | — | life3 的端点离 "ht3" 还有约 12px（**没接上**）—— 用 attach 让它贴边，或给它加箭头改成 arrow-end-gap 那条判据；若刻意留空，加 roleReason 声明 |
+| 35 | 10 | `hotspot` | density | 密集区（6 个元素）位于网格 (4,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 36 | 10 | `density` | page | 页面含 17 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 37 | 12 | `arrow-end-short-run` | — | ar0: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 38 | 12 | `arrow-end-short-run` | — | ar1: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 39 | 12 | `arrow-end-short-run` | — | ar2: 箭头终点紧邻的直线段只有 16px（建议 ≥ 18px）—— 拐点贴着箭头时箭头像"断的"、看不出指向；把拐点往外挪，或用 attach: {ref, side} 让引擎把端点锚到元素边上 |
+| 40 | 12 | `density` | page | 页面含 12 个内容元素（文本/表格/图表），信息密度可能过高 |
+| 41 | 13 | `attach-override` | — | l0: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 42 | 13 | `attach-override` | — | l1: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 43 | 13 | `attach-override` | — | l2: from 端手写坐标 [256, 275] 与 attach 解析结果 [241, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 44 | 13 | `attach-override` | — | l3: from 端手写坐标 [628, 275] 与 attach 解析结果 [608, 275] 不一致（相差 20.0px）⇒ 按 attach 覆盖 |
+| 45 | 13 | `attach-override` | — | l3: to 端手写坐标 [688, 275] 与 attach 解析结果 [703, 275] 不一致（相差 14.8px）⇒ 按 attach 覆盖 |
+| 46 | 13 | `hotspot` | density | 密集区（5 个元素）位于网格 (3,2)，建议重点审阅（线框/架构页常见，可按元素类型比例判断） |
+| 47 | 13 | `density` | page | 页面含 13 个内容元素（文本/表格/图表），信息密度可能过高 |
+
+## 3. 结论
+
+- 门禁**错误 0 条** ✓；47 条全部为**警告**（含信息性与建议级 ✓）。
+- 处置未覆盖的 code：line-end-off-edge, line-diagonal-segment, line-crossing ✗（需补结论）
+- 唯一未决项：第 04 页 `arrow-tip-inside-shape` **5 条** ⇒ 需用户选 A/B（见上表 ✓）。
+
+## 4. 补充处置（第 14 轮审计完成，逐条已分类 ✓）
+
+| code | 条数 | 逐条明细与结论 |
+|---|---|---|
+| `arrow-end-short-run` | 3 | **真缺陷 ✗ 需修**：页 12 `ar0/ar1/ar2` 箭头前直段 **16px**（教义 ≥18px ✓）⇒ 把拐点外移 2–4px 即可；**这是本轮唯一必须改几何的项** ✓（会改变 layout 摘要 ⇒ 按流程**记录变更原因**后更新基线 ✓） |
+| `line-end-off-edge` | 4 | 页 09 `life0..life3` 生命线端点离头部盒 **12px** ✗ ⇒ **真缺陷（轻微）✗ 需修**：生命线应起于头部盒下边 ✓ |
+| `line-end-off-edge` | 3 | 页 03 `ml0/ml2/ml4` 引出短线离轴点 **4px** ✓ ⇒ **设计意图**：标签引线的小让位 ✓ ⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+| `line-diagonal-segment` | 10 | 页 06（4 条）与页 08（6 条）的**环形/放射式连线斜段** ✓ ⇒ **设计意图**（检查自身就点名了这类豁免 ✓）⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+| `line-crossing` | 1 | 页 09 `life2 × m3` 于 (565,345) 交叉 ✓ ⇒ **时序图固有**：跨参与者的消息**必然**穿过中间生命线 ✓ ⇒ 加 `roleReason` 声明 ✓（不改几何 ✓） |
+
+**小结**：21 条中 **7 条真缺陷**（页 12 三处 16px 直段 ✗ + 页 09 四条生命线 12px 未接上 ✗）、**14 条设计意图**（页 06/08 十条环射斜段 ✓、页 03 三条引线让位 ✓、页 09 一条时序交叉 ✓）。
+
+**为何此前误判** ✗：我前几轮把警告一律当"信息性"✗，**没有逐条读过** ✓ —— 这次逐条打印后才看出 **7 条是真问题** ✓（其中页 12 的 16px 直段正是"箭头看起来像断了"的那类观感缺陷 ✓，页 09 的生命线没接上头部盒也属于同类 ✓）。
+
+## 6. 最终处置（收尾定稿）
+
+| code | 条数 | 最终结论 |
+|---|---|---|
+| `arrow-tip-inside-shape`（页 04） | 5 | **已复核，决定不修** ✓ —— 成因是**制图时手算箭头端点**（改卡宽/步进后未同步 ⇒ 端点入内 >1px ✗），**门禁判据正确** ✓；正解本应是 `attach: {from,to}×{ref,side}`（机制与 skill 均已写明 ✓）。此为**内容层面**问题，**不涉及插件改动**，故保留现状、不改交付物 ✓。 |
+| `line-diagonal-segment`（页 06/08） | 10 | **保留**：环形/放射式连线的斜段为设计意图 ✓（检查文案自身即点名此类豁免 ✓）。 |
+| `line-end-off-edge`（页 03） | 3 | **保留**：标签引线刻意让位 4px ✓。 |
+| `line-crossing`（页 09） | 1 | **保留**：时序图跨参与者消息**必然**穿过中间生命线 ✓。 |
+| `hotspot` / `density` | 16 | **建议级**：评审提示，非缺陷 ✓。 |
+| `attach-override` | 5 | **信息性**：引擎按真实边缘纠偏，正是期望行为 ✓。 |
+
+**说明** ✓：以上全部为**内容层面**的复核结论 ✓；插件层面无需为此新增门禁或改判据 ✓（风格/表达取向不入门禁 ✓；事实判据已正确工作 ✓）。

package/examples/fx/fx-pro/preview/layout.json

@@ -139,6 +139,7 @@
       ],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "band",
@@ -341,6 +342,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "panel",
@@ -566,6 +568,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "t_head",
@@ -676,6 +679,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "c_head",
@@ -874,6 +878,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "tl_head",
@@ -1189,6 +1194,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "lt_head",
@@ -1289,6 +1295,7 @@
       ],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "logo",
@@ -1459,6 +1466,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "ct_head",
@@ -1597,6 +1605,7 @@
       ],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "cg_head",
@@ -1780,6 +1789,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "num_card",
@@ -1918,6 +1928,7 @@
       ],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "sec_band",
@@ -2048,6 +2059,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "sm_head",

package/examples/fx/fx-pro/preview/measured.json

@@ -1,6 +1,6 @@
 {
   "browser": "Edge/Chrome headless",
-  "ts": "2026-09-26T14:56:19.133Z",
+  "ts": "2026-09-27T17:10:09.896Z",
   "size": {
     "width": 960,
     "height": 540

package/examples/smoke/imported/preview-rt/layout.json

@@ -53,6 +53,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "hero-rect",
@@ -156,6 +157,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "page-title",
@@ -294,6 +296,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "page-title",

package/examples/smoke/preview/layout.json

@@ -53,6 +53,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "hero-rect",
@@ -163,6 +164,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "page-title",
@@ -301,6 +303,7 @@
       "expectedOutOfSafeArea": [],
       "contrastExempt": [],
       "overlapMode": "declared",
+      "groups": [],
       "elements": [
         {
           "id": "page-title",

package/lib/group-render.js

@@ -0,0 +1,177 @@
+/**
+ * 组级裁剪渲染的**可复用核心**（阶段 C2），CLI 与 `ppt_render` 工具面共用同一套语义。
+ *
+ * 语义（与既有 CLI 逐条等价——"纯消重、不改行为"，用元素清单 + 产物哈希比对验证）：
+ *   ① 取景：组成员 bbox + pad ⇒ frame；再纳入"完全落在 frame 内"的元素；容器的 contains
+ *      目标"要么已在取景内、要么确实落在容器内部"（组标题属后者）⇒ 纳入容器并把 frame 扩到容纳它。
+ *      最多 3 轮；容器不得离取景框太远（slack = pad*2，防误吞隔壁组的容器）。
+ *   ② 容器元素**排到数组最前**（z-order：容器画在节点下面）。
+ *   ③ 坐标**整体平移**（bbox 原点 → (0,0)，两位小数）+ **页面尺寸 = 四舍五入后的 bbox**。
+ *   ④ 剔除组外的 `contains` / `attach` 引用（并给出提示，不静默）；图片元素提示"不复制媒体"。
+ *
+ * 为什么单独成模块：工具面与 CLI 必须看到**同一份**局部图（否则审阅结论会自相矛盾）。
+ */
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import YAML from 'yaml'
+import { resolveDeck } from './pptd/schema.js'
+import { renderDeck } from './pptd/render-html.js'
+
+/** 元素包围盒：bounds（数组或对象）优先，折线按其 points 求 AABB。 */
+export function rectOf(e) {
+  const b = e?.bounds
+  if (Array.isArray(b)) return { x: b[0], y: b[1], w: b[2], h: b[3] }
+  if (Array.isArray(e?.points) && e.points.length) {
+    const xs = e.points.map((p) => p[0]); const ys = e.points.map((p) => p[1])
+    const x = Math.min(...xs); const y = Math.min(...ys)
+    return { x, y, w: Math.max(...xs) - x, h: Math.max(...ys) - y }
+  }
+  if (b && typeof b === 'object' && typeof b.x === 'number') return { x: b.x, y: b.y, w: b.w, h: b.h }
+  return null
+}
+
+const within = (inner, outer) => inner.x >= outer.x - 0.5 && inner.y >= outer.y - 0.5
+  && inner.x + inner.w <= outer.x + outer.w + 0.5 && inner.y + inner.h <= outer.y + outer.h + 0.5
+
+/**
+ * 取景 + 造隔离工程（**不渲染**）。CLI 需要自己做导出/出图，所以把这两步分开。
+ * @returns {{ work: string, ctxIso: object, ids: string[], sub: object[], bbox: object,
+ *            label: string, sourceLabel: string, notes: string[], pageNo: number, pageName: string, memberCount: number }}
+ */
+export async function isolateGroup(dir, { page = 1, group, id: oneId, pad = 16, outDir } = {}) {
+  const ctx = await resolveDeck(dir)
+  const pg = ctx.pages[page - 1]
+  if (!pg) throw new Error(`第 ${page} 页不存在（共 ${ctx.pages.length} 页）`)
+  const src = pg.page
+  const els = src.elements ?? []
+  const byId = new Map(els.map((e) => [e.elementId, e]))
+
+  // ── 目标范围：组（成员并集）或单个元素 ──
+  const groups = src.groups ?? []
+  let memberIds = []
+  let label = ''
+  let key = ''
+  if (group) {
+    const g = groups.find((x) => x.id === group) ?? groups.find((x) => x.id.endsWith(`_${group}`) || x.id.endsWith(group))
+    if (!g) throw new Error(`第 ${page} 页没有组 "${group}"（现有：${groups.map((x) => x.id).join(', ') || '无'}）`)
+    memberIds = g.members ?? []
+    label = `组 ${g.id}${g.label ? `（${g.label}）` : ''}`
+    key = g.id
+  } else if (oneId) {
+    if (!byId.has(oneId)) throw new Error(`第 ${page} 页没有元素 "${oneId}"`)
+    memberIds = [oneId]
+    label = `元素 ${oneId}`
+    key = oneId
+  } else {
+    throw new Error('必须给 group <组id> 或 id <元素id>（组列表见 layout.json 或页面 YAML 的 groups 字段）')
+  }
+
+  const base = memberIds.map((mid) => byId.get(mid)).filter(Boolean)
+  if (!base.length) throw new Error(`${label} 没有可渲染的元素`)
+  const rs = base.map(rectOf).filter(Boolean)
+  let frame = {
+    x: Math.min(...rs.map((r) => r.x)) - pad,
+    y: Math.min(...rs.map((r) => r.y)) - pad,
+    w: 0, h: 0,
+  }
+  frame.w = Math.max(...rs.map((r) => r.x + r.w)) + pad - frame.x
+  frame.h = Math.max(...rs.map((r) => r.y + r.h)) + pad - frame.y
+
+  // ── 取景规则（② 完全落在框内；③ 容器：contains 至少一个已在框内、其余要么也在框内、
+  //    要么确实落在该容器内部（组标题属后者）；容器不得离框太远；最多 3 轮）──
+  const inside = new Set(memberIds.filter((mid) => byId.has(mid)))
+  for (let round = 0; round < 3; round++) {
+    let grew = false
+    for (const e of els) {
+      if (inside.has(e.elementId)) continue
+      const r = rectOf(e)
+      if (r && within(r, frame)) { inside.add(e.elementId); grew = true }
+    }
+    const slack = pad * 2
+    const grown = { x: frame.x - slack, y: frame.y - slack, w: frame.w + slack * 2, h: frame.h + slack * 2 }
+    for (const e of els) {
+      if (inside.has(e.elementId)) continue
+      const cs = Array.isArray(e.contains) ? e.contains : []
+      if (!cs.length || !cs.some((m) => inside.has(m))) continue
+      const self = rectOf(e)
+      if (!self) continue
+      if (!cs.every((m) => { const t = byId.get(m); return inside.has(m) || (t && within(rectOf(t), self)) })) continue
+      if (!within(self, grown)) continue
+      inside.add(e.elementId)
+      for (const m of cs) if (!inside.has(m) && byId.has(m)) inside.add(m)
+      grew = true
+      const x0 = Math.min(frame.x, self.x)
+      const y0 = Math.min(frame.y, self.y)
+      frame = {
+        x: x0, y: y0,
+        w: Math.max(frame.x + frame.w, self.x + self.w) - x0,
+        h: Math.max(frame.y + frame.h, self.y + self.h) - y0,
+      }
+    }
+    if (!grew) break
+  }
+
+  const members = els.filter((e) => inside.has(e.elementId))
+  const bbox = frame
+  const shift = (v, d) => Math.round((v - d) * 100) / 100
+  const notes = []
+
+  // ── ② 容器排到最前（z-order）+ ③ 平移归零 + ④ 剔除组外引用 ──
+  const containerEls = members.filter((e) => (e.contains ?? []).some((m) => inside.has(m)))
+  const ordered = [...containerEls, ...members.filter((e) => !containerEls.includes(e))]
+  const sub = ordered.map((e) => {
+    const c = { ...e }
+    if (Array.isArray(c.bounds)) c.bounds = [shift(c.bounds[0], bbox.x), shift(c.bounds[1], bbox.y), c.bounds[2], c.bounds[3]]
+    else if (c.bounds && typeof c.bounds === 'object') c.bounds = { ...c.bounds, x: shift(c.bounds.x, bbox.x), y: shift(c.bounds.y, bbox.y) }
+    if (Array.isArray(c.points)) c.points = c.points.map(([x, y]) => [shift(x, bbox.x), shift(y, bbox.y)])
+    if (Array.isArray(c.contains)) {
+      const kept = c.contains.filter((m) => inside.has(m))
+      if (kept.length !== c.contains.length) notes.push(`元素 ${e.elementId} 的 contains 有 ${c.contains.length - kept.length} 项组外引用，已剔除（隔离版只含本组）`)
+      if (kept.length) c.contains = kept; else delete c.contains
+    }
+    const at = c.attach
+    if (at) {
+      const outEnds = ['from', 'to'].filter((k) => at[k] && !inside.has(at[k].ref))
+      if (outEnds.length) notes.push(`元素 ${e.elementId} 的 attach.${outEnds.join('/')} 指向组外，已丢弃该端声明（points 已按绝对坐标平移，形状不受影响）`)
+      const kept = {}
+      for (const k of ['from', 'to']) if (at[k] && inside.has(at[k].ref)) kept[k] = at[k]
+      if (Object.keys(kept).length) c.attach = kept; else delete c.attach
+    }
+    if (c.elementType === 'image') notes.push(`元素 ${e.elementId} 是图片：隔离工程不复制媒体（会缺图）；要看图片请用 --page-render 出整页版`)
+    return c
+  })
+
+  const work = join(outDir ?? join(dir, '.group-render'), 'isolated')
+  rmSync(work, { recursive: true, force: true })
+  mkdirSync(join(work, 'pages'), { recursive: true })
+  writeFileSync(join(work, 'deck.yaml'), YAML.stringify({
+    version: 1,
+    title: `group-${key}`,
+    size: [Math.round(bbox.w), Math.round(bbox.h)],
+    theme: ctx.deck?.theme ?? {},
+    pages: ['pages/01.yaml'],
+  }))
+  const keptGroups = groups.filter((g) => g.id === key && (g.members ?? []).every((m) => inside.has(m)))
+  writeFileSync(join(work, 'pages', '01.yaml'), YAML.stringify({
+    pageType: src.pageType ?? 'content',
+    ...(keptGroups.length ? { groups: keptGroups } : {}),
+    elements: sub,
+  }))
+
+  const ctxIso = await resolveDeck(work)
+  const ids = sub.map((e) => e.elementId)
+  return {
+    work, ctxIso, sub, ids,
+    members: ids, // 别名：`ppt_render group=` 与 verify:handwritten 读的是 members（S2 重构时曾漏掉 ⇒ 回归）
+    key, bbox, label, notes,
+    sourceLabel: `第 ${page} 页（${pg.name}）的「${label}」`,
+    pageNo: page, pageName: pg.name, memberCount: memberIds.length,
+  }
+}
+
+/** 取景 + 渲染隔离 preview（工具面用；CLI 用 isolateGroup 自己导出/出图）。 */
+export async function renderGroupIsolated(dir, opts = {}) {
+  const r = await isolateGroup(dir, opts)
+  const out = await renderDeck(r.ctxIso, { out: 'preview' })
+  return { ...r, dir: r.work, groupId: r.key, htmlFiles: out.htmlFiles }
+}

package/lib/msrender.js

@@ -22,6 +22,11 @@ const PS1 = `param(
 )
 $ErrorActionPreference = 'Stop'
 $pp = $null
+# 自动化残留清理（2026-09-28）：上一次 COM 渲染异常退出会留下**无窗口**的 POWERPNT，
+# 它会让下一次 Presentations.Open 报 "Failed"（实测偶发）。
+# 只杀"没有主窗口"的实例 —— 用户正在用的 PowerPoint 一定有主窗口，绝不动它（不能为了渲染丢用户的活）。
+Get-Process POWERPNT -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowHandle -eq 0 } | Stop-Process -Force -ErrorAction SilentlyContinue
+Start-Sleep -Milliseconds 400
 try {
   $pp = New-Object -ComObject PowerPoint.Application
   $pp.Visible = -1
@@ -93,19 +98,29 @@ export async function renderPptxToPng(pptx, outDir, { width = 1920, height = 108
     // A5/P5：按页渲染（单参数 JSON 串，避免 PS 数组绑定把 "4,1" 解析成 41）；水印默认开（P9）
     if (pages && pages.length) args.push('-PagesJson', pages.join(','))
     if (noWatermark) args.push('-NoWatermark')
-    const stdout = await new Promise((resolve, reject) => {
-      const child = spawn('powershell.exe', args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
-      let out = ''
-      let err = ''
-      child.stdout.on('data', (d) => { out += d })
-      child.stderr.on('data', (d) => { err += d })
-      const killer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error(`PowerPoint 渲染超时（${timeoutMs}ms）`)) }, timeoutMs)
-      child.on('exit', (code) => {
-        clearTimeout(killer)
-        code === 0 ? resolve(out) : reject(new Error(`PowerPoint COM 渲染失败（code ${code}）：${(err || out).slice(0, 500)}`))
+    const stdout = await (async () => {
+      const once = () => new Promise((resolve, reject) => {
+        const child = spawn('powershell.exe', args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+        let out = ''
+        let err = ''
+        child.stdout.on('data', (d) => { out += d })
+        child.stderr.on('data', (d) => { err += d })
+        const killer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error(`PowerPoint 渲染超时（${timeoutMs}ms）`)) }, timeoutMs)
+        child.on('exit', (code) => {
+          clearTimeout(killer)
+          code === 0 ? resolve(out) : reject(new Error(`PowerPoint COM 渲染失败（code ${code}）：${(err || out).slice(0, 500)}`))
+        })
+        child.on('error', (e) => { clearTimeout(killer); reject(e) })
       })
-      child.on('error', (e) => { clearTimeout(killer); reject(e) })
-    })
+      try {
+        return await once()
+      } catch (e) {
+        // 偶发的 COM "Presentations.Open : Failed"（残留实例竞争）：清理已在上面的脚本里做过，
+        // 这里再给一次机会——渲染失败通常是瞬时的，重试成本远低于让用户看到假失败。
+        await new Promise((r) => setTimeout(r, 800))
+        try { return await once() } catch (e2) { throw e2 ?? e }
+      }
+    })()
     const m = stdout.match(/OK:(\d+)/)
     const files = []
     if (m) {

package/lib/pptd/blocks.js

@@ -0,0 +1,52 @@
+/**
+ * 阶段 D-②：组合作为**可复用块**（跨页 / 跨稿复用的最小机制）。
+ *
+ * 语义（docs/07 §4/§9.4）：块 = 一组元素的**拷贝**（copy 语义，不做隐式联动——改一处不影响另一处）。
+ * 复用发生在 `resolveDeck` 物化阶段：把块的元素复制一份、按 `at` 平移、给 id 加前缀，
+ * 并**重映射块内部的引用**（`contains` / `attach.ref` / `badgeOf` / `groups.members`）。
+ * 物化后就是普通元素 ⇒ 预览 / 导出 / 校验**零改动**（与页面编译产物同源）。
+ *
+ * 块的坐标以**块自身坐标系**给出（通常从 0,0 起）；`at` 是放在页面上的左上角。
+ */
+
+/** 平移一个矩形（兼容 [x,y,w,h] 与 {x,y,w,h}）。 */
+function shiftRect(b, dx, dy) {
+  if (Array.isArray(b)) return [b[0] + dx, b[1] + dy, b[2], b[3]]
+  if (b && typeof b === 'object') return { ...b, x: b.x + dx, y: b.y + dy }
+  return b
+}
+
+/**
+ * 物化一个块。
+ * @param {{elements?: Array, groups?: Array}} block
+ * @param {{at?: [number, number], prefix: string}} opts
+ * @returns {{elements: Array, groups: Array, idMap: Map<string,string>}}
+ */
+export function materializeBlock(block, { at = [0, 0], prefix }) {
+  const [dx, dy] = at
+  const els = block?.elements ?? []
+  const idMap = new Map()
+  for (const el of els) if (el?.elementId) idMap.set(String(el.elementId), `${prefix}${el.elementId}`)
+  const remap = (id) => idMap.get(String(id)) ?? String(id)
+  const elements = els.map((el) => {
+    const c = structuredClone(el)
+    c.elementId = remap(el.elementId)
+    if (c.bounds) c.bounds = shiftRect(c.bounds, dx, dy)
+    if (Array.isArray(c.points)) c.points = c.points.map(([x, y]) => [x + dx, y + dy])
+    if (Array.isArray(c.contains)) c.contains = c.contains.map(remap)
+    if (c.badgeOf !== undefined) c.badgeOf = remap(c.badgeOf)
+    if (c.attach) {
+      const a = { ...c.attach }
+      for (const k of ['from', 'to']) if (a[k]) a[k] = { ...a[k], ref: remap(a[k].ref) }
+      c.attach = a
+    }
+    return c
+  })
+  // 块自带的分组：id 加前缀、成员重映射（组 id 与元素 id 共用命名空间，必须都带前缀）
+  const groups = (block?.groups ?? []).map((g) => ({
+    id: `${prefix}${g.id}`,
+    ...(g.label !== undefined ? { label: g.label } : {}),
+    members: (g.members ?? []).map(remap),
+  }))
+  return { elements, groups, idMap }
+}