dsh-ppt-studio 1.1.5 → 1.2.1

package/lib/pptd/route-geometry.js

@@ -0,0 +1,120 @@
+/**
+ * 路由几何（G1：把族管线的两个后处理接到**显式 elements**（纯手画）通路）
+ *
+ * 背景：`orthogonalize`（斜段→直角折线）与 `arrowEndRuns`（箭头端紧邻段 ≥ ARROW_MIN_RUN）此前
+ * 图 04 折点离端点 7px、图 09 竖线穿字）。本模块把两者封装成**一个带守卫的入口**给手画用。
+ *
+ * 为什么不直接调用族的组合 `orthogonalize(arrowEndRuns(orthogonalize(pts), arrow))`：
+ *   · **守卫 1（n < 3）**：`arrowEndRuns` 的 `fix(n-2, n-1)` 在 n=2 时退化为 `fix(0,1)` ——
+ *     它会去**挪起点**，把短直线改短、包围盒跟着变。实测效果：既有 smoke 断言
+ *     "连线·水平线 包围盒 cy=0" 由绿转红。直线没有"拐点"可挪 ⇒ 直接原样返回。
+ *   · **守卫 2（折返）**：族里这套组合是为"路由产生的折角"设计的。用在简单 L 形上会造出**折返尖刺**：
+ *     实测 [(200,300),(400,300),(400,307)]（末段仅 7px）→ [(200,300),(400,300),(400,289),(400,307)]
+ *     （先上 11px 再下 18px）。折返 100% 是缺陷 ⇒ 一旦结果含折返就**保留原样**，
+ *     把"箭头前直段过短"交给门禁检查去拦（而不是悄悄画出一根刺）。
+ *
+ * 例外（与族一致）：本身就是"环/放射"语义的图形（cycle 外环弦、放射线）**豁免正交化** ——
+ * 这里由 `isAxisAligned()` 判定：折线中只要存在斜段，就视为有意为之，调用方跳过本模块。
+ */
+// ── 本模块**自持**这三个纯量（F1 解耦：原先族与手画共用，现由手画侧提供、族反向 import）──
+/**
+ * 箭头端的"直线段最短长度"。
+ * 用户实测反馈：拐点离箭头太近时，箭头看起来像"断的"、也看不出指向（附图那根线就是在箭头处拐弯）。
+ * 规则：带箭头的端点，其**紧邻的那一段**必须 ≥ ARROW_MIN_RUN 像素；不够就把相邻的**拐点**沿该段反向挪远。
+ * 只挪拐点、不动端点（attach 语义不变），且挪动方向沿该段自身 ⇒ 拐点仍落在原来的走廊/间隙里。
+ */
+export const ARROW_MIN_RUN = 18
+export function arrowEndRuns(pts, arrow) {
+  const p = (pts ?? []).map(([x, y]) => [x, y])
+  if (p.length < 2) return p
+  // 让 p[i]→p[j] 这一段至少有 MIN 长（挪 i，不动 j）
+  const fix = (i, j) => {
+    const d = Math.hypot(p[j][0] - p[i][0], p[j][1] - p[i][1])
+    if (d === 0 || d >= ARROW_MIN_RUN) return
+    const ux = (p[j][0] - p[i][0]) / d
+    const uy = (p[j][1] - p[i][1]) / d
+    let nx = p[j][0] - ux * ARROW_MIN_RUN
+    let ny = p[j][1] - uy * ARROW_MIN_RUN
+    // **夹紧（X1-b）**：挪动后的拐点不得越过相邻点 p[i-1] —— 越过就形成"折返尖刺"
+    //（用户实测图 10 顶端多出一根线：91.1 → 73.1 → 118.1 的折返就是这里挪出来的）。
+    // 宁可这一段略短于 18px，也不许出现折返（折返 100% 是缺陷，短直段只是观感弱一点）。
+    if (i - 1 >= 0) {
+      const px = p[i - 1][0]
+      const py = p[i - 1][1]
+      const sameX = Math.abs(px - p[i][0]) < 0.5 && Math.abs(p[i][0] - p[j][0]) < 0.5
+      const sameY = Math.abs(py - p[i][1]) < 0.5 && Math.abs(p[i][1] - p[j][1]) < 0.5
+      if (sameX) ny = uy > 0 ? Math.min(ny, py) : Math.max(ny, py)
+      else if (sameY) nx = ux > 0 ? Math.min(nx, px) : Math.max(nx, px)
+    }
+    p[i] = [nx, ny]
+  }
+  const n = p.length
+  if (arrow === true || arrow === 'end' || arrow === 'both') fix(n - 2, n - 1) // 箭头在末端
+  if (arrow === 'both') fix(1, 0) // 两端箭头：起点那一段
+  return p
+}
+
+/**
+ * 斜段 → 直角折线：把每一段非轴对齐的线拆成"先横后竖"两段（插入一个拐点）。
+ *
+ * **这是设计定死的规则**（用户提出、2026-09-28 敲定）：引擎产出的折线**永远轴对齐**。
+ *   · 正交路由是这套图的"工程感"来源，也让"竖/横段 AABB 宽或高为 0"这条重叠判定前提成立；
+ *   · 斜段会让**箭头方向不确定**（截图里那种"看不出指向"的线就是斜段+拐弯叠加）；
+ *   · **唯一例外**：本身就是"环/放射"语义的图形（`cycle` 的外环弦、`funnel` 的梯形斜边），
+ *     前者用 `orthogonal: false` 显式声明豁免，后者画的是 custGeom 形状而不是箭头折线。
+ * 用途：兜住 `arrowEndRuns` 之类的后处理——它们只挪拐点，可能把**前一段**拉斜（用户实测发现的回归）。
+ */
+export function orthogonalize(pts) {
+  if (!pts || pts.length < 2) return pts
+  const out = [pts[0]]
+  for (let i = 1; i < pts.length; i++) {
+    const [x0, y0] = out[out.length - 1]
+    const [x1, y1] = pts[i]
+    if (Math.abs(x1 - x0) < 0.5 || Math.abs(y1 - y0) < 0.5) { out.push([x1, y1]); continue }
+    out.push([x1, y0], [x1, y1]) // 先横后竖
+  }
+  return out
+}
+
+/** 折线是否全部轴对齐（斜段 ⇒ 属"环/放射"语义，应豁免正交化） */
+export function isAxisAligned(pts) {
+  const p = pts ?? []
+  return p.every((q, i) => i === 0
+    || Math.abs(q[0] - p[i - 1][0]) < 0.5 || Math.abs(q[1] - p[i - 1][1]) < 0.5)
+}
+
+/** 折返检测：相邻两段**共线且反向**（折返 100% 是缺陷，不许被后处理造出来） */
+export function hasFoldback(pts) {
+  const p = pts ?? []
+  for (let i = 2; i < p.length; i++) {
+    const ax = p[i - 1][0] - p[i - 2][0]
+    const ay = p[i - 1][1] - p[i - 2][1]
+    const bx = p[i][0] - p[i - 1][0]
+    const by = p[i][1] - p[i - 1][1]
+    const la = Math.hypot(ax, ay)
+    const lb = Math.hypot(bx, by)
+    if (!la || !lb) continue
+    const collinear = Math.abs(ax * by - ay * bx) < 1e-6 * la * lb
+    if (collinear && ax * bx + ay * by < 0) return true
+  }
+  return false
+}
+
+/**
+ * 手画折线的路由后处理（带两道守卫）。
+ * @param {Array<[number,number]>} pts 折线点列（绝对坐标）
+ * @param {boolean|'end'|'both'} arrow 箭头配置（原样透传，'both' 表示两端）
+ * @returns {Array<[number,number]>} 处理后的点列（守卫不通过时原样返回）
+ */
+export function routePolyline(pts, arrow) {
+  const raw = (pts ?? []).map(([x, y]) => [x, y])
+  // **契约（2026-09 实测确认，smoke 有 6 条专项断言守着）**：
+  // 2 点直连线是**受支持的连接符** —— 引擎导出为 <p:cxnSp>（带 flipH/flipV），斜向也完全合法。
+  // **不许正交化它**：否则 cxnSp 数归零、方向专项断言全崩（本轮实测）。
+  // 因此只有**折线（≥3 点）**才过正交化 + 箭头端最短直段。
+  if (raw.length < 3) return raw
+  const fixed = orthogonalize(arrowEndRuns(orthogonalize(raw), arrow))
+  // 折返守卫：族算法用在 L 形上会造"先上后下"尖刺 ⇒ 含折返就退回原样，
+  // 交给门禁 arrow-end-short-run 报出（引擎不造缺陷、门禁负责报缺陷）。
+  return hasFoldback(fixed) ? raw : fixed
+}

package/lib/pptd/schema.js

@@ -44,11 +44,22 @@ const TEXT_STYLE_KEYS = ['fontSize', 'fontFamily', 'color', 'bold', 'italic', 'a
 const ELEMENT_KEYS = {
   text: ['content'],
   shape: ['kind', 'fill', 'line'],
-  line: ['points', 'arrow', 'line'],
+  line: ['points', 'arrow', 'line', 'attach'],
   image: ['src', 'fit'],
   table: ['cols', 'rows', 'header'],
   chart: ['chart'],
 }
+/**
+ * 阶段 A（docs/08 §1）：**所有元素通用**的结构声明键。
+ * 语义：`contains` 视觉容器 / `badgeOf` 徽章归属 / `roleReason` 角色覆盖理由。
+ * 几何反验证在 `src/pptd/relations.js`（本文件只做类型与引用存在性等**结构**校验）。
+ */
+const STRUCT_KEYS = ['contains', 'badgeOf', 'roleReason']
+/** attach 的边枚举：与 geometry 层的判定共用一份（relations.js），避免两处枚举漂移。 */
+import { ATTACH_SIDES } from './relations.js'
+import { profileToTheme } from './style-profile.js'
+import { materializeBlock } from './blocks.js'
+import { measureText } from './layout.js'
 
 /**
  * shape.kind 白名单（v0.9.1 候选 A：常见 prst 直通）。
@@ -58,6 +69,7 @@ export const SHAPE_KINDS = [
   'rect', 'roundRect', 'ellipse', 'triangle', 'custGeom',       // 原始 + 自定义几何（v0.11 候选 C）
   'rightArrow', 'leftArrow', 'upArrow', 'downArrow', 'leftRightArrow', // 箭头
   'pentagon', 'hexagon', 'chevron', 'parallelogram', 'diamond', 'octagon', 'star5', // 多边形/星
+  'notchedRightArrow', // 流程图常用（阶段 A 补齐：用户真实稿每页 4–8 个）
   'flowchartProcess', 'flowchartDecision', 'flowchartData', 'flowchartTerminator', // 流程图
 ]
 
@@ -234,6 +246,8 @@ export function validatePage(page, file) {
   if (page.version !== undefined && page.version !== 1) errors.push(`[${file}] page.version must be 1`)
   const elements = Array.isArray(page.elements) ? page.elements : []
   const ids = new Set()
+  // 声明引用的存在性统一**延后**校验：声明可能写在其引用的元素之前，边扫边查会误报。
+  const deferredRefs = []
   elements.forEach((el, i) => {
     const path = `[${file}] elements[${i}]`
     if (!el || typeof el !== 'object') { errors.push(`${path}: expected object`); return }
@@ -251,6 +265,31 @@ export function validatePage(page, file) {
     if (el.role !== undefined && !['background', 'content', 'decoration'].includes(el.role)) {
       errors.push(`${path}.role: background|content|decoration（层叠语义：背景/内容/装饰；decoration 完全豁免重叠报告）`)
     }
+    // ── 阶段 A：结构声明字段（docs/08 §1）──
+    // 类型/形状在这里查；引用存在性延后；几何反验证在 relations.js。
+    if (el.roleReason !== undefined && (typeof el.roleReason !== 'string' || el.roleReason.trim() === '')) {
+      errors.push(`${path}.roleReason: non-empty string（role 覆盖推断值时的理由；会进入门禁报告"声明复核"段）`)
+    }
+    if (el.contains !== undefined) {
+      if (!Array.isArray(el.contains) || el.contains.length === 0 || el.contains.some((x) => typeof x !== 'string' || x === '')) {
+        errors.push(`${path}.contains: non-empty array of element ids（视觉容器：声明"我包住这些元素"）`)
+      } else {
+        const dup = [...new Set(el.contains.filter((x, i, a) => a.indexOf(x) !== i))]
+        if (dup.length) errors.push(`${path}.contains: 重复声明 ${dup.join('/')}`)
+        for (const cid of el.contains) {
+          if (cid === el.elementId) errors.push(`${path}.contains: 不能包含自己`)
+          else deferredRefs.push({ path: `${path}.contains`, field: 'id', ref: cid })
+        }
+      }
+    }
+    if (el.badgeOf !== undefined) {
+      if (typeof el.badgeOf !== 'string' || el.badgeOf === '') errors.push(`${path}.badgeOf: element id string（徽章/标签的归属对象）`)
+      else if (el.badgeOf === el.elementId) errors.push(`${path}.badgeOf: 不能归属自己`)
+      else deferredRefs.push({ path: `${path}.badgeOf`, field: 'id', ref: el.badgeOf })
+    }
+    if (el.attach !== undefined && type !== 'line') {
+      errors.push(`${path}.attach: 只对 elementType: line 有效（把线段两端锚到元素边上）`)
+    }
     if (type === 'text') {
       validateText(el, path, errors)
       // B1 修复（反馈二 ★）：元素级残留样式键 → 明确报错（此前静默忽略按默认 18pt 度量，
@@ -261,7 +300,7 @@ export function validatePage(page, file) {
       }
     }
     if (type === 'shape') validateShape(el, path, errors)
-    if (type === 'line') validateLine(el, path, errors)
+    if (type === 'line') validateLine(el, path, errors, deferredRefs)
     if (type === 'image') {
       if (typeof el.src !== 'string') errors.push(`${path}.src: required string`)
       if (el.fit !== undefined && !['cover', 'contain', 'fill'].includes(el.fit)) errors.push(`${path}.fit: cover|contain|fill`)
@@ -269,6 +308,53 @@ export function validatePage(page, file) {
     if (type === 'table') validateTable(el, path, errors)
     if (type === 'chart') validateChart(el, path, errors)
   })
+  // ── 阶段 A：延后校验的结构声明引用（顺序无关） ──
+  for (const d of deferredRefs) {
+    if (!ids.has(d.ref)) errors.push(`${d.path}: "${d.ref}" 不是本页元素 id（防呆：结构声明必须指向真实元素）`)
+  }
+  // ── 阶段 A：groups（逻辑组合，可嵌套）──
+  // 这里做**结构**校验（类型/唯一性/存在性/唯一直接父组/无环）；
+  // 几何反验证（包含、附着、徽章）在 src/pptd/relations.js。
+  if (page.groups !== undefined) {
+    if (!Array.isArray(page.groups)) {
+      errors.push(`[${file}] groups: array of {id, label?, members: [元素或组 id]}（逻辑组合：剪枝/审阅/声明作用域）`)
+    } else {
+      const gids = new Set()
+      page.groups.forEach((g, i) => {
+        const gp = `[${file}] groups[${i}]`
+        if (!g || typeof g !== 'object' || Array.isArray(g)) { errors.push(`${gp}: expected object {id, members}`); return }
+        if (typeof g.id !== 'string' || g.id === '') errors.push(`${gp}.id: required non-empty string`)
+        else if (gids.has(g.id)) errors.push(`${gp}.id: duplicate "${g.id}"`)
+        else if (ids.has(g.id)) errors.push(`${gp}.id: "${g.id}" 与元素 id 同名（组与元素共用同一命名空间）`)
+        else gids.add(g.id)
+        if (g.label !== undefined && typeof g.label !== 'string') errors.push(`${gp}.label: string（人类可读用途，审阅输出里显示）`)
+        if (!Array.isArray(g.members) || g.members.length === 0 || g.members.some((m) => typeof m !== 'string' || m === '')) {
+          errors.push(`${gp}.members: non-empty array of element/group ids`)
+        }
+      })
+      const parentOf = new Map()
+      page.groups.forEach((g, i) => {
+        if (!g || typeof g !== 'object' || typeof g.id !== 'string') return
+        for (const m of Array.isArray(g.members) ? g.members : []) {
+          if (typeof m !== 'string' || m === '') continue
+          if (!ids.has(m) && !gids.has(m)) errors.push(`[${file}] groups[${i}].members: "${m}" 既不是元素也不是组 id`)
+          else if (parentOf.has(m)) errors.push(`[${file}] groups[${i}].members: "${m}" 同时属于组 "${parentOf.get(m)}" 与 "${g.id}"（只允许一个直接父组）`)
+          else parentOf.set(m, g.id)
+        }
+      })
+      // 嵌套无环（DFS）
+      const byId = new Map(page.groups.filter((g) => g && typeof g.id === 'string').map((g) => [g.id, g]))
+      const state = new Map()
+      const dfs = (id, stack) => {
+        if (state.get(id) === 'done') return
+        if (state.get(id) === 'visiting') { errors.push(`[${file}] groups: 嵌套成环 ${[...stack, id].join(' → ')}`); return }
+        state.set(id, 'visiting')
+        for (const m of byId.get(id)?.members ?? []) if (byId.has(m)) dfs(m, [...stack, id])
+        state.set(id, 'done')
+      }
+      for (const id of [...byId.keys()].sort()) dfs(id, [])
+    }
+  }
   if (page.rowBounds !== undefined) errors.push(`[${file}] rowBounds: unsupported in v1`)
   if (page.expectedOverlaps !== undefined) {
     if (!Array.isArray(page.expectedOverlaps)) {
@@ -283,6 +369,10 @@ export function validatePage(page, file) {
           for (const idX of po.pair) {
             if (!ids.has(idX)) errors.push(`[${file}] expectedOverlaps[${i}]: "${idX}" 不是本页元素 id（防呆：声明必须指向真实元素）`)
           }
+          // 阶段 A：reason 缺失只算**警告**（docs/08 §1.1：缺失 ⇒ 警告，不破坏既有 deck），类型错则当场报错
+          if (po.reason !== undefined && (typeof po.reason !== 'string' || po.reason.trim() === '')) {
+            errors.push(`[${file}] expectedOverlaps[${i}].reason: non-empty string（机器可读的设计理由；会进入门禁报告"声明复核"段）`)
+          }
         }
       })
     }
@@ -378,16 +468,39 @@ function validateShape(el, path, errors) {
   }
 }
 
-function validateLine(el, path, errors) {
+function validateLine(el, path, errors, deferredRefs = []) {
   const pts = Array.isArray(el.points) ? el.points : null
-  const has = el.points ? pts.length === 2 && pts.every((p) => Array.isArray(p) && p.length === 2 && p.every((n) => typeof n === 'number')) : (typeof el.x1 === 'number' && typeof el.y1 === 'number' && typeof el.x2 === 'number' && typeof el.y2 === 'number')
-  // P2-3：line 仅支持 2 点（多点折线静默截断是真缺陷 → 显式报错引导拆分）
-  if (el.points && Array.isArray(el.points) && el.points.length !== 2) {
-    errors.push(`${path}.points: 仅支持 2 点 [[x1,y1],[x2,y2]]（多点折线不支持，请拆分为多条 line）`)
-  } else if (!has) {
-    errors.push(`${path}.points: [[x1,y1],[x2,y2]] exactly 2 points, or x1,y1,x2,y2 numbers`)
-  }
-  if (el.arrow !== undefined && typeof el.arrow !== 'boolean') errors.push(`${path}.arrow: boolean`)
+  const ptsOk = pts !== null && pts.length >= 2
+    && pts.every((p) => Array.isArray(p) && p.length === 2 && p.every((n) => typeof n === 'number' && Number.isFinite(n)))
+  const xyOk = typeof el.x1 === 'number' && typeof el.y1 === 'number' && typeof el.x2 === 'number' && typeof el.y2 === 'number'
+  // 阶段 A：>2 点折线已支持（导出为 custGeom 开放路径，见 docs/08 §6）；非法点列仍显式报错
+  if (el.points !== undefined && !ptsOk) {
+    errors.push(`${path}.points: [[x,y],…] 至少 2 点、每点两个有限数字（>2 点为折线，阶段 A 起支持）`)
+  } else if (el.points === undefined && !xyOk) {
+    errors.push(`${path}.points: [[x,y],…] 至少 2 点，或 x1,y1,x2,y2 numbers`)
+  }
+  if (el.arrow !== undefined && !(typeof el.arrow === 'boolean' || el.arrow === 'end' || el.arrow === 'both')) {
+    errors.push(`${path}.arrow: true|false|'end'|'both'（true 等价 'end'；'both' = 两端箭头）`)
+  }
+  if (el.line?.dash !== undefined && !['solid', 'dash', 'dot', 'dashDot'].includes(el.line.dash)) {
+    errors.push(`${path}.line.dash: solid|dash|dot|dashDot`)
+  }
+  // ── attach：把两端锚到元素边上（导出时解析成坐标；几何反验证在 relations.js）──
+  const a = el.attach
+  if (a === undefined) return
+  if (!a || typeof a !== 'object' || Array.isArray(a)) {
+    errors.push(`${path}.attach: {from?: {ref, side}, to?: {ref, side}}（side: ${ATTACH_SIDES.join('|')}）`)
+    return
+  }
+  for (const end of ['from', 'to']) {
+    const spec = a[end]
+    if (spec === undefined) continue
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) { errors.push(`${path}.attach.${end}: {ref, side}`); continue }
+    if (typeof spec.ref !== 'string' || spec.ref === '') errors.push(`${path}.attach.${end}.ref: element id string`)
+    else deferredRefs.push({ path: `${path}.attach.${end}`, field: 'ref', ref: spec.ref })
+    if (!ATTACH_SIDES.includes(spec.side)) errors.push(`${path}.attach.${end}.side: ${ATTACH_SIDES.join('|')}`)
+  }
+  if (a.from === undefined && a.to === undefined) errors.push(`${path}.attach: 至少给 from 或 to 之一`)
 }
 
 function validateTable(el, path, errors) {
@@ -490,6 +603,7 @@ export async function resolveDeck(dir) {
   const colors = theme.colors ?? {}
   const textStyles = theme.textStyles ?? {}
   const pages = []
+  const blocksExpanded = new Map() // 阶段 D-②：记录每页展开了哪些块（供报告/自证）
   for (const ref of deck.pages) {
     const file = join(dir, ref)
     if (!existsSync(file)) throw fail(`page file missing: ${ref}`)
@@ -503,6 +617,27 @@ export async function resolveDeck(dir) {
     if (perr) throw perr
     const terr = themeRefCheck(page, theme, ref)
     if (terr.length) throw fail(terr)
+    // ── 阶段 D-②：`blocks`（组合作为可复用块）物化 —— copy 语义、按 at 平移、id 加前缀并重映射内部引用 ──
+    if (page.blocks !== undefined) {
+      if (!Array.isArray(page.blocks)) throw fail(`[${ref}] blocks: 数组（每项 {name, at?: [x, y]}）`)
+      page.blocks.forEach((use, i) => {
+        const name = use?.name
+        if (typeof name !== 'string' || !name) throw fail(`[${ref}] blocks[${i}].name: 必填字符串（deck.blocks 里的块名）`)
+        const block = deck.blocks?.[name]
+        if (!block) throw fail(`[${ref}] blocks[${i}]: deck.blocks 里没有块 "${name}"（现有：${Object.keys(deck.blocks ?? {}).join(', ') || '无'}）`)
+        const at = Array.isArray(use.at) ? use.at : [0, 0]
+        if (!(at.length === 2 && at.every((n) => typeof n === 'number'))) throw fail(`[${ref}] blocks[${i}].at: [x, y] numbers`)
+        const out = materializeBlock(block, { at, prefix: `bk${i + 1}_` })
+        page.elements = [...(page.elements ?? []), ...out.elements]
+        if (out.groups.length) page.groups = [...(page.groups ?? []), ...out.groups]
+        const doc = blocksExpanded.get(ref) ?? []
+        doc.push({ name, at, elements: out.elements.length, groups: out.groups.length })
+        blocksExpanded.set(ref, doc)
+      })
+    }
+    // ── 阶段 B：`diagram` 物化（IR → 普通元素 + 结构关系）──
+    // 展开在这里 ⇒ normalizePage / 预览 / 导出 / verify **全部零改动**，预览与成品天然同源（docs/12 §5）。
+    // 没有 `diagram` 的页完全不进这段 ⇒ 既有工程逐字节不变。
     pages.push({ file: join(dir, ref), ref, page, name: (page.title ?? ref.replace(/\.yaml$/, '')).toString(), index: pages.length })
   }
   const resolveColor = (v) => {

package/lib/pptd/style-profile.js

@@ -0,0 +1,133 @@
+/**
+ * 阶段 D-①：样式档案（从**参考稿**观测 → 令牌 → 喂回引擎）。
+ *
+ * 立场（docs/07 D2 铁律）：**裁决优先级 = 用户口头要求 > 参考稿 > 其他**；引擎自身没有审美。
+ * 本模块只做"观测 + 归纳"，把参考稿里**实际出现**的取色、线宽、字号阶梯、圆角归纳成令牌；
+ * 再由 `profileToTheme()` 折成一个普通 theme 对象交给既有的 `styleProfileFrom()`——
+ * 于是引擎侧**零改动**（它只是换了一份令牌来源）。
+ *
+ * 数据来源：`observeFromLayout(layout)` 从 layout.json（导入参考稿后渲染出的那份）观测；
+ * 也可由调用方直接给 `extractStyleProfile({fills, lineWidths, fontSizes, radii, bg})`。
+ */
+
+/** 中性色判定（与 verify.js 的口径一致：RGB 各分量差 ≤ 8）。 */
+function isNeutral(hex) {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex ?? ''))
+  if (!m) return true
+  const v = parseInt(m[1], 16)
+  const r = (v >> 16) & 0xff
+  const g = (v >> 8) & 0xff
+  const b = v & 0xff
+  return Math.abs(r - g) <= 8 && Math.abs(g - b) <= 8 && Math.abs(r - b) <= 8
+}
+const norm = (hex) => {
+  const m = /^#?([0-9a-fA-F]{6})$/.exec(String(hex ?? ''))
+  return m ? `#${m[1].toUpperCase()}` : null
+}
+const median = (arr) => {
+  if (!arr.length) return null
+  const s = [...arr].sort((a, b) => a - b)
+  return s[Math.floor((s.length - 1) / 2)]
+}
+
+/**
+ * 从 **deck（原始 DSL 元素）** 观测——比 layout.json 准：原始元素带 `line.width` 与 `content.fontSize`，
+ * 而 layout.json 的形状快照只有 `{shape, fill, path, rotation}`（实测 lineWidths 会是空的）。
+ */
+export function observeFromDeck(ctx) {
+  const fills = []
+  const lineWidths = []
+  const fontSizes = []
+  const radii = []
+  const bg = norm(ctx?.deck?.theme?.colors?.bg) ?? null
+  // 关键：`$themeRef` 必须先**解析成实际色值**再统计。第一版直接读 `el.fill`，
+  // 于是 `$primary` 这种未解析字符串被归一化成中性色、还挤掉真正的调色板（实测 palette[0] 排错）。
+  const resolve = (v) => {
+    try { return norm(ctx?.resolveColor?.(v)) ?? norm(v) ?? null } catch { return norm(v) ?? null }
+  }
+  for (const p of ctx?.pages ?? []) {
+    for (const el of p.page?.elements ?? []) {
+      const f = typeof el.fill === 'string' ? resolve(el.fill) : (el.fill?.color ? resolve(el.fill.color) : null)
+      if (f) fills.push(f)
+      if (el.line?.width) lineWidths.push(Number(el.line.width))
+      if (el.content?.fontSize) fontSizes.push(Number(el.content.fontSize))
+      if (typeof el.kind === 'string' && /roundRect|ellipse/.test(el.kind)) radii.push(8)
+    }
+  }
+  return { fills: fills.filter(Boolean), lineWidths, fontSizes, radii, bg }
+}
+
+/** 便捷入口：deck（resolveDeck 结果）一步到档案 / theme。 */
+export function profileFromDeck(ctx) {
+  return extractStyleProfile(observeFromDeck(ctx))
+}
+
+/** 从 layout.json 观测"参考稿里实际出现了什么"。 */
+export function observeFromLayout(layout) {
+  const fills = []
+  const lineWidths = []
+  const fontSizes = []
+  const radii = []
+  let bg = null
+  for (const page of layout?.pages ?? []) {
+    if (!bg && typeof page.background === 'string') bg = norm(page.background)
+    for (const el of page.elements ?? []) {
+      if (typeof el.fill === 'string') fills.push(norm(el.fill) ?? el.fill)
+      if (el.fill && typeof el.fill === 'object' && typeof el.fill.color === 'string') fills.push(norm(el.fill.color))
+      if (el.line?.width) lineWidths.push(Number(el.line.width))
+      if (el.style?.fontSize) fontSizes.push(Number(el.style.fontSize))
+      if (el.kind === 'roundRect') radii.push(8)
+      if (el.radius) radii.push(Number(el.radius))
+    }
+  }
+  return { fills: fills.filter(Boolean), lineWidths, fontSizes, radii, bg }
+}
+
+/**
+ * 归纳成样式档案（确定性：按**出现频次**排序，频次相同按色值字典序）。
+ * @returns {{palette: string[], ink: string, bg: string, neutral: string, lineWidth: number, fontSize: number, radius: number, observed: object}}
+ */
+export function extractStyleProfile(observed = {}) {
+  const counts = new Map()
+  for (const c of observed.fills ?? []) counts.set(c, (counts.get(c) ?? 0) + 1)
+  const all = [...counts.entries()].sort((a, b) => (b[1] - a[1]) || String(a[0]).localeCompare(String(b[0])))
+  const colorful = all.filter(([c]) => !isNeutral(c)).map(([c]) => c)
+  const neutrals = all.filter(([c]) => isNeutral(c)).map(([c]) => c)
+  const bg = norm(observed.bg) ?? neutrals[0] ?? '#FFFFFF'
+  // 墨色：中性色里**最深**的那个（参考稿里的文字/描边色）
+  const ink = [...neutrals].sort((a, b) => parseInt(a.slice(1), 16) - parseInt(b.slice(1), 16))[0] ?? '#1F2937'
+  const lineWidth = median((observed.lineWidths ?? []).filter((n) => n > 0)) ?? 1
+  const fontSize = median((observed.fontSizes ?? []).filter((n) => n >= 8)) ?? 14
+  const radius = median((observed.radii ?? []).filter((n) => n >= 0)) ?? 8
+  return {
+    palette: colorful.length ? colorful : ['#2563EB'],
+    ink,
+    bg,
+    neutral: neutrals.find((c) => c !== bg) ?? '#F1F5F9',
+    lineWidth: Number(lineWidth),
+    fontSize: Number(fontSize),
+    radius: Number(radius),
+    observed: { fills: [...counts.keys()].sort(), counts: Object.fromEntries(all) },
+  }
+}
+
+/** 档案 → 普通 theme 对象（交给既有的 styleProfileFrom，引擎零改动）。 */
+export function profileToTheme(profile) {
+  const colors = {}
+  colors.primary = profile.palette?.[0] ?? '#2563EB'
+  if (profile.palette?.[1]) colors.accent = profile.palette[1]
+  if (profile.palette?.[2]) colors.soft = profile.palette[2]
+  colors.text = profile.ink ?? '#1F2937'
+  colors.bg = profile.bg ?? '#F8FAFC'
+  return {
+    colors,
+    textStyles: { body: { fontSize: profile.fontSize ?? 14, color: '$text' } },
+    line: { width: profile.lineWidth ?? 1 },
+    radius: profile.radius ?? 8,
+  }
+}
+
+/** 便捷入口：layout.json 一步到 theme。 */
+export function themeFromLayout(layout) {
+  return profileToTheme(extractStyleProfile(observeFromLayout(layout)))
+}

package/lib/scaffold.js

@@ -69,7 +69,7 @@ elements:
 #   # commands: moveTo|lnTo|quadBezTo|cubicBezTo|arcTo(wR/hR/stAng/swAng)|close；坐标 = 路径空间抽象单位
 \`\`\`
 
-### line（bounds 可省略；**仅 2 点**，多点折线请拆成多条 line——P2-3）
+### line（bounds 可省略；≥2 点，>2 点为折线；arrow: true 或 'both'；line.dash 虚线；attach 可把两端锚到元素边）
 \`\`\`yaml
 - elementId: arrow
   elementType: line
@@ -119,6 +119,59 @@ contrastExempt:              # P1-1：已确认对比度正常但启发式误报
 overlapMode: declared        # declared（默认）| lenient（草稿缓冲：未声明仅提示）
 \`\`\`
 
+## 结构声明（复杂图：写"结构"，不要手算坐标）
+一页里有 ≥3 个盒子 + 连线/容器/徽章时，**优先用结构声明**——引擎推导关系并做几何反验证，
+比你逐对写 expectedOverlaps 更省、更不易漏。规则：**声明 + 通过几何反验证 = 豁免；验证不过 ⇒ 声明作废并按普通冲突报错**（不自证豁免）。推导出的豁免**不落盘**（每次现算，文档里看不到、也不用维护）。
+\`\`\`yaml
+groups:                        # 逻辑组合（可嵌套 ≤3 层）：审计/剪枝的单位，也是"当成一个整体"的块
+  - id: g_input
+    label: 输入层
+    members: [box_a, box_b]    # 成员 = 元素 id 或**组 id**；一个成员只能有一个直接父组
+elements:
+  - elementId: zone
+    elementType: shape
+    kind: roundRect
+    contains: [box_a, box_b, ln1]   # 视觉容器：我真包住这些（几何必须严格包含，否则按冲突报错）
+  - elementId: chip
+    elementType: shape
+    badgeOf: zone                   # 徽章/标签归属：必须相交、面积 ≤ 0.5×被归属者、不得盖满
+    roleReason: "标题胶囊压在容器顶边"  # role 覆盖推断值时的理由（进"声明复核"段）
+  - elementId: ln1
+    elementType: line
+    points: [[240, 240], [260, 200]]    # 可省略：两端都写 attach 时由引擎算
+    attach:                             # 锚到元素边（**优先于**手写 points）
+      from: {ref: box_a, side: right}   # side: top|right|bottom|left
+      to:   {ref: box_b, side: left}    # 手写坐标被改写时，门禁报告出 attach-override 警告（不静默覆盖）
+expectedOverlaps:
+  - pair: [chip, zone]
+    reason: "标题胶囊压在容器顶边"        # 缺失只算警告（不破坏既有工程）
+\`\`\`
+- **传递闭包**：A ⊇ B ⊇ C ⇒ A×C 自动豁免——外层容器**不必枚举深后代**（嵌套组合的关键）。
+- **图专属机械检查**（用了结构声明的页才启用）：重合元素 duplicate-element、文本互压 text-over-text、线穿盒 line-through-box、箭头脱靶 arrow-not-on-edge。
+- **没用到结构声明的页面行为与从前完全一致**（门控）——你可以只在新页上逐步采用。
+- 复杂图导出基元：points >2 点 = 折线（一帧 custGeom 开放路径，不是多条拼的）；arrow: 'both' = 两端箭头（arrow: true 等价 'end'）；line.dash: solid|dash|dot|dashDot；kind: notchedRightArrow（流程图常用）。
+
+
+不要再指望引擎替你算几何 —— 按需读 skills/ppt-studio-diagram/（调度手册 mechanisms.md + 12 份子 skill 配方），用显式 elements 把图拼出来。
+这是受支持的正式路径，不是退路（13 页实测：零族依赖、门禁 0 错、与旧族产物同内容对照 10 更好 / 1 持平 / 2 持平偏旧 / 0 变差）。
+
+关键机制（都在手画侧）：
+- 连边优先 attach: {from: {ref, side}, to: {ref, side}} —— 引擎锚到真实边缘（斜边图形也不例外），不要手算像素；
+- 折线（≥3 点）自动正交化 + 箭头端自动保证 ≥18px 直段；2 点直连线是连接符（导出 cxnSp），保持直线、不要正交化它；
+- 容器/分组：contains 声明相邻层；语义底板用 role: decoration；刻意穿过用 roleReason 说明；
+- 收工前逐条读门禁警告（line-cross-text / arrow-end-short-run / line-end-off-edge / arrow-tip-inside-shape / line-crossing / line-diagonal-segment）；
+- 历史档案：族机制原始设计见 docs/07 / docs/12 / docs/13（已废弃，仅对照）。
+- **组合作为可复用块（阶段 D）**：deck.blocks.<名> = {elements, groups?} 定义块，页面里 blocks: [{name: <名>, at: [x, y]}] 复用它（**copy 语义**：id 自动加 bk<n>_ 前缀、内部 contains / attach / badgeOf / groups 引用同步重映射、按 at 平移；改一份不影响另一份）。
+- **手写折线/箭头（不属于任何族、完全自由发挥时）同样要守这几条**（引擎内部已经这么做，手写时请照做，否则会出现"箭头像断了/看不出指向"这类观感问题）：
+  1. 折线**只用轴对齐段**（横段/竖段）——环形、放射、漏斗这类**本身就是斜的**图形除外（那类斜线是设计意图）；
+  2. **箭头端紧邻的那一段必须 ≥ 18px 直线**，拐点不要贴着箭头（附着线用 attach 锚边即可，不必手算像素点）；
+  3. 连线端点点在元素边上时优先用 attach: {from: {ref, side}, to: {ref, side}} —— 引擎会把它解析到真实边缘，比手写坐标稳；
+  4. **边标签贴着它标注的那条线**放（线上方或线下方 6px 左右，或竖线旁边 8px），不要放在两条线中间；标签文字短就用小框（框宽≈文字宽+8），别用大框占位；
+  5. 语义性的背景带 / 引导环 / 分组底板用 role: decoration（完全豁免重叠判定），**不要**用 expectedOverlaps 去掩盖"压字/压盒"；
+  6. 一页可以**既写结构声明又手写元素**（缝合页）；assistant 想要家族库没有的图，就按上面几条手写 elements 拼出来——这是被支持的路径，不是退路。
+  7. **斜边图形**（parallelogram / triangle / diamond）直接用 attach 就行：引擎会接到**真实斜边**上（不是包围盒边）——不要自己算斜边坐标；按包围盒边取点会出现"箭头插进图形里"或"离图形差一截"。
+  8. 门禁对"箭头插进图形里"（arrow-tip-inside-shape）与"端点离目标 2–10px 没接上"（arrow-end-gap）只给**警告**（不是错误）——因为这两种**都可能是刻意设计**：确实要插进去 / 刻意留空时，给该线加 roleReason: "…" 声明即可不再提示。
+
 ## 层叠角色推断（不在 expectedOverlaps 的规则）
 - text/table/chart = content；shape/image = background（承载）；line = line（引脚线/箭头）。
 - content×content 重叠 → ERROR content-collision（不可声明豁免）。

package/lib/tools.js

@@ -468,9 +468,27 @@ export function registerTools(ctx) {
   reg({
     name: 'ppt_render',
     description: '渲染 deck 项目 → preview/*.html 与 layout.json（数字审阅的数据源）。每页制作后运行',
-    parameters: { dir: dirSchema, debug: { type: 'boolean', description: '文本框描边调试（默认 false）' } },
+    parameters: { dir: dirSchema, debug: { type: 'boolean', description: '文本框描边调试（默认 false）' }, group: { type: 'string', description: '只对某个**组合**出隔离裁剪图（组 id，见 layout.json 或页面 YAML 的 groups）：渲染到 <dir>/.group-render/isolated/preview。整页缩略图会掩盖"线落边/压字/留白"这类小尺寸缺陷，审阅组内细节时用它；省略则渲染整册' }, page: { type: 'number', description: '配合 group：组所在页码（1 起，缺省 1）' } },
     output: markdownResult(),
-    async execute({ dir, debug }) {
+    async execute({ dir, debug, group, page }) {
+      if (group) {
+        // 组级裁剪渲染（C2）：与 CLI `npm run render:group` **共用同一套取景规则**（src/group-render.js）
+        const { renderGroupIsolated } = await import('./group-render.js')
+        try {
+          const r = await renderGroupIsolated(dir, { page: page ?? 1, group })
+          return [
+            `✓ 组级隔离渲染完成：组 ${r.groupId}${r.label ? `（${r.label}）` : ''}｜取景 ${r.members.length} 个元素｜bbox ${Math.round(r.bbox.x)},${Math.round(r.bbox.y)} ${Math.round(r.bbox.w)}×${Math.round(r.bbox.h)}（含 pad）`,
+            '',
+            `**这是第 ${page ?? 1} 页某个组合的局部图，不是整页**（整页缩略图会掩盖线落边/压字/留白这类小尺寸缺陷）。`,
+            '',
+            ...r.htmlFiles.map((f) => `  - ${f}`),
+            '',
+            '下一步：read_image 导出的 PNG，或指向该隔离目录做截图复核组内细节。',
+          ].join('\n')
+        } catch (error) {
+          return `✗ 组级隔离渲染失败：\n${errText(error)}`
+        }
+      }
       try {
         const ctx0 = await loadCtx(dir)
         const r = await renderDeck(ctx0, { debug: !!debug })