dsh-ppt-studio 1.1.5 → 1.2.1

package/lib/pptd/export-pptx.js

@@ -10,12 +10,16 @@
  * - 1px = 1pt；EMU = pt × 12700。
  * - 讲稿（2026-09-14 新增）：页面 `notes:` 文本 → 标准 pptx 备注页（notesSlide + notesMaster）。
  *   无 `notes:` 的工程**不产出任何备注部件**（产物与旧实现一致 ⇒ 老工程零变化）；parity 里 notesExp/notesOut 自证。
+ * - 折线/箭头两端/虚线（2026-09-27 阶段 A）：`line.points` 支持 N 点（>2 点走 `a:custGeom` **开放路径**）；
+ *   `arrow: true | 'end' | 'both'`；`line.dash: solid | dash | dot | dashDot`。
+ *   **只用 2 点 + `arrow: true` + 无 dash 的工程产物逐字节不变**（仍旧走 straightConnector1 那条码路）。
  */
 import { writeFile, readFile } from 'node:fs/promises'
 import { join, isAbsolute } from 'node:path'
 import { createHash } from 'node:crypto'
 import { zipWrite } from '../zips.js'
 import { normalizePage } from './layout.js'
+import { onSide, rectOf, onAttachSide } from './relations.js'
 import { chartData, chartColors, chartIssue, resolveChart } from './svgCharts.js'
 import { auditNativeCharts, chartFrameXml, chartPartNames, embeddedWorkbook, nativeChartRels, nativeChartXml } from './nativeChart.js'
 
@@ -37,6 +41,22 @@ export async function exportPptx(ctx, { out = 'out.pptx', engine = 'pptd' } = {}
   // straightConnector1 在 OOXML 里**只按包围盒的左上→右下**绘制，方向必须靠 flipH/flipV 表达；
   // 漏写 → 反向斜率/镜像（cross1×cross2 会重合成一条线）。这里逐条从写出的 XML 反推端点自证。
   const lineProof = { exp: 0, out: 0, wrong: [] }
+  // 附着线自证（阶段 A-④/⑤）：声明 `attach` 的线，**导出侧从实际 points 独立复核**端点落在被引用元素的对应边上。
+  // 不信归一化层——那正是"解析了 attach 但 side/ref 用错"会漏掉的地方。
+  const attachProof = { exp: 0, out: 0, wrong: [] }
+  // 折线（>2 点）自证（2026-09-27 阶段 A）：custGeom 开放路径的每条边都要从**写出的 XML**反推回页面坐标
+  // 与源 points 一致（否则"预览对、成品折错/镜像"这类事故会静默通过——与 lineProof 同一条纪律）。
+  // 另：arrowHeadExp/arrowHeadsOut = 声明 `both` 的**头端**数 vs 产物 XML 里的 `<a:headEnd` 计数。
+  const polyProof = { exp: 0, out: 0, wrong: [] }
+  const arrowProof = { headExp: 0, headOut: 0 }
+  const fieldWarnings = new Set()
+  const warnField = (id, msg) => {
+    const line = `元素 "${id}": ${msg}`
+    if (!fieldWarnings.has(line)) {
+      fieldWarnings.add(line)
+      report.warnings.push(line)
+    }
+  }
   UID = 1000
 
   // 媒体部件命名（2026-09-26 修复"同名静默错图"）——**整册共享**（不能按页各算一套，否则同一 srcPath
@@ -91,11 +111,45 @@ export async function exportPptx(ctx, { out = 'out.pptx', engine = 'pptd' } = {}
         case 'text': shapes.push(textSp(el, report, ctx.minFontSize)); break
         case 'shape': shapes.push(shapeSp(el)); break
         case 'line': {
-          lineProof.exp++
-          shapes.push(connectorSp(el, lineProof))
+          // attach 解析接入点（relations.resolveAttach）：声明了 `attach` 但还没算出 `points` 的线，
+          // 在归一化阶段由 relations.js 解析成 `points`（`attach` 优先于手写 points，并另行提示）。
+          // 导出侧**只认 points**——这里不做任何 attach 几何推导（保持导出器是纯写盘层）。
+          if (!el.points && el.attach) report.warnings.push(`元素 "${el.id}": 声明了 attach 但归一化层未解析出 points（请检查 relations.resolveAttach 是否已接入 normalizePage）`)
+          const isPoly = Array.isArray(el.points) && el.points.length > 2
+          // 退化点（points 不足 2 点）：schema 是第一道闸；漏到导出层 ⇒ **明确拒绝**（警告 + 不产坏 XML），
+          // 绝不静默写出一条 undefined 坐标的线（NaN/undefined 进 OOXML = PowerPoint 报修复）。
+          if (!isPoly && (!Array.isArray(el.points) || el.points.length < 2)) {
+            report.warnings.push(`元素 "${el.id}": points 不足 2 点（${JSON.stringify(el.points)}）⇒ 跳过导出该项（schema 应已拒收；请检查校验是否被绕过）`)
+            break
+          }
+          if (isPoly) {
+            polyProof.exp++
+            shapes.push(polylineSp(el, polyProof, arrowProof, warnField))
+          } else {
+            lineProof.exp++
+            shapes.push(connectorSp(el, lineProof, arrowProof, warnField))
+          }
+          // 阶段 A-⑤：附着线单独计数并**在导出侧独立复核**（不信归一化层的结果）
+          // 判据：声明了 attach 的每个端点，其**实际 points 端点**必须落在被引用元素的对应边上。
+          // 这能抓到"归一化解析了 attach 但 side/ref 用错"这类只有几何能证伪的错误。
+          if (el.attach) {
+            attachProof.exp++
+            const ends = [[el.points?.[0], el.attach.from], [el.points?.[el.points.length - 1], el.attach.to]]
+            let ok = true
+            for (const [pt, spec] of ends) {
+              if (!spec) continue
+              const ref = els.find((e) => e.id === String(spec.ref))
+              if (!ref || !Array.isArray(pt)) { ok = false; attachProof.wrong.push(`${el.id}: attach.${String(spec.side)} 引用 "${spec.ref}" 找不到或端点缺失`); break }
+              if (!onAttachSide(ref, String(spec.side), pt, 1.5)) {
+                ok = false
+                attachProof.wrong.push(`${el.id}: 端点 [${Math.round(pt[0])}, ${Math.round(pt[1])}] 不在 "${spec.ref}" 的 ${spec.side} 边（tol=1.5）`)
+                break
+              }
+            }
+            if (ok) attachProof.out++
+          }
           break
-        }
-        case 'image': {
+        }        case 'image': {
           counts.image++
           const rId = addMedia(el.src)
           shapes.push(picSp(el, rId))
@@ -252,6 +306,15 @@ export async function exportPptx(ctx, { out = 'out.pptx', engine = 'pptd' } = {}
   const notesParts = Object.keys(files).filter((k) => /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(k))
   const notesOut = notesParts.length
   const notesRelOk = slides.filter((s) => s.notes).every((s) => String(files[`ppt/slides/_rels/slide${slides.indexOf(s) + 1}.xml.rels`]).includes(`notesSlide${s.notesNo}.xml`))
+  // 多端箭头（阶段 A §7）：声明 `arrow: both` 的**头端**数（每条 both 线应写 1 个 headEnd）== 产物里的 `<a:headEnd` 计数。
+  // 从产物反推（不是数中间变量）——"生成器以为写了、写盘路径把它丢了"这一类只有回读才抓得到。
+  let arrowHeadsOut = 0
+  for (let i = 0; i < slides.length; i++) {
+    const raw = files[`ppt/slides/slide${i + 1}.xml`]
+    const txt = typeof raw === 'string' ? raw : String(raw ?? '')
+    arrowHeadsOut += (txt.match(/<a:headEnd\b/g) ?? []).length
+  }
+  const linesWrongAll = [...lineProof.wrong, ...polyProof.wrong]
   // 媒体 parity（2026-09-26 新增）：**不同 srcPath 数 == 包内媒体部件数**。
   // 为什么必须单独加一条：图数量 parity（imagesExp/imagesOut）只数 `<p:pic>`，两张不同的图塌成同一个部件时
   // 它依然是 2/2、ok=true（实测）。而"两张不同的图被写成同一个部件"= 成品里静默用错图，正是本插件最不能出的错。
@@ -324,6 +387,11 @@ export async function exportPptx(ctx, { out = 'out.pptx', engine = 'pptd' } = {}
   report.parity = {
     tablesExp, tablesOut, imagesExp, imagesOut, illegalFrames: illegal,
     linesExp: lineProof.exp, linesOut: lineProof.out, linesWrong: lineProof.wrong.length,
+    // 折线（>2 点）与多端箭头（阶段 A 新增；无此类元素的工程全部为 0，既有断言不受影响）
+    polyLinesExp: polyProof.exp, polyLinesOut: polyProof.out, polyLinesWrong: polyProof.wrong.length,
+    // 附着线（阶段 A-④/⑤：attach 驱动坐标，导出侧独立复核端点落在被引用元素的对应边上）
+    attachedLinesExp: attachProof.exp, attachedLinesOut: attachProof.out, attachedLinesWrong: [...attachProof.wrong],
+    arrowEndsExp: arrowProof.headExp, arrowEndsOut: arrowHeadsOut,
     notesExp, notesOut,
     mediaExp: mediaExpSet.size, mediaOut,
     textExp, textMissing, chartShapesExp, chartShapesOut,
@@ -333,6 +401,9 @@ export async function exportPptx(ctx, { out = 'out.pptx', engine = 'pptd' } = {}
     chartDataMismatch: chartAudit.dataMismatch, chartRelsMissing: [...chartAudit.relsMissing, ...chartRelMissing],
     ok: tablesExp === tablesOut && imagesExp === imagesOut && illegal === 0 &&
       lineProof.exp === lineProof.out && lineProof.wrong.length === 0 &&
+      polyProof.exp === polyProof.out && polyProof.wrong.length === 0 &&
+      attachProof.exp === attachProof.out && attachProof.wrong.length === 0 &&
+      arrowProof.headExp === arrowHeadsOut && linesWrongAll.length === 0 &&
       notesExp === notesOut && notesRelOk && mediaExpSet.size === mediaOut &&
       textMissing.length === 0 && chartShapesExp === chartShapesOut &&
       chartFramesMissing.length === 0 && chartAudit.ok && chartRelMissing.length === 0,
@@ -366,13 +437,189 @@ function xfrm(x, y, w, h, rot = 0, flips = '') {
  * 描边属性。`arrow` 的 `<a:tailEnd>` **必须写在 `<a:ln>` 内部**（2026-09-14 修复）——
  * 旧实现把它拼在 `</a:ln>` 之后，PowerPoint 直接忽略 ⇒ 箭头全部消失（预览有、成品没有）。
  * OOXML 子元素顺序：fill → prstDash → join → headEnd → tailEnd。
+ * `arrow` 取值（阶段 A）：`true|'end'` ⇒ 只写 tailEnd（既有语义，产物不变）；`'both'` ⇒ headEnd + tailEnd；
+ * `line.dash`（阶段 A）：solid（缺省，**不写元素**）| dash | dot | dashDot ⇒ `<a:prstDash val="…">`。
  */
 function lineSpPr(line, arrow = false) {
   const w = Math.round((line?.width ?? 1) * EMU)
-  const tail = arrow ? '<a:tailEnd type="triangle" w="med" len="med"/>' : ''
-  return '<a:ln w="' + w + '"><a:solidFill><a:srgbClr val="' + hex(line?.color ?? '#000000') + '"/></a:solidFill>' + tail + '</a:ln>'
+  const a = arrowState(arrow)
+  const dash = dashVal(line)
+  const dashXml = dash ? '<a:prstDash val="' + dash + '"/>' : ''
+  const head = a === 'both' ? '<a:headEnd type="triangle" w="med" len="med"/>' : ''
+  const tail = a !== 'none' ? '<a:tailEnd type="triangle" w="med" len="med"/>' : ''
+  return '<a:ln w="' + w + '"><a:solidFill><a:srgbClr val="' + hex(line?.color ?? '#000000') + '"/></a:solidFill>' + dashXml + head + tail + '</a:ln>'
+}
+
+// ── 阶段 A：折线 / 箭头两端 / 虚线（2026-09-27）─────────────────────────────
+/** 箭头端语义白名单：true ≡ 'end'（向后兼容，产物不变）｜'both' 两端｜false/undefined 无箭头。 */
+const ARROW_STATES = ['none', 'end', 'both']
+
+/**
+ * `arrow` 归一化：`true` 与 `'end'` 同义（既有产物不变）；`'both'` = 两端。
+ * 非法值（如 `arrow: 'bogus'`）：schema 层负责拒收；万一漏到导出层 ⇒ 明确返回 'none'（**绝不静默产出坏 XML**），
+ * 且由调用方 warnField 把这次降级写进 report.warnings（不静默）。
+ */
+function arrowState(arrow) {
+  if (arrow === true || arrow === 'end') return 'end'
+  if (arrow === 'both') return 'both'
+  return 'none'
+}
+
+/** 虚线映射。OOXML ST_PresetLineDashVal 合法值：solid/dot/dash/dashDot/...（我们只放行白名单四种）。 */
+const DASH_VALUES = { solid: 'solid', dash: 'dash', dot: 'dot', dashDot: 'dashDot' }
+
+/**
+ * `line.dash` → prstDash 值。
+ * 缺省/`solid` ⇒ 返回 null ⇒ **完全不写 `<a:prstDash>`**（既有产物逐字节不变的关键）。
+ * `dashDot` 拼写严格（OOXML 是 dashDot 不是 dashdot）；非法值 ⇒ null + 由调用方 warnField 报出降级。
+ */
+function dashVal(line) {
+  const d = line?.dash
+  if (d === undefined || d === null || d === 'solid') return null
+  return DASH_VALUES[d] ?? null
+}
+
+/** 非法字段值告警（schema 是第一道闸；导出层是第二道 —— 两道都不许静默）。 */
+function validateLineFields(el, warn) {
+  const raw = el?.arrow
+  const okArrow = raw === undefined || raw === null || typeof raw === 'boolean' || ARROW_STATES.includes(raw)
+  if (!okArrow && warn) warn(el.id, `arrow 取值非法（${JSON.stringify(raw)}）⇒ 按"无箭头"导出；合法值：true | 'end' | 'both'`)
+  const d = el?.line?.dash
+  const okDash = d === undefined || d === null || Object.prototype.hasOwnProperty.call(DASH_VALUES, d)
+  if (!okDash && warn) warn(el.id, `line.dash 取值非法（${JSON.stringify(d)}）⇒ 按 solid 导出；合法值：solid | dash | dot | dashDot`)
+}
+
+/**
+ * N 点折线（>2 点）→ `a:custGeom` **开放路径**（moveTo + 若干 lnTo，**不 close**），描边、无填充，
+ * 箭头挂在这条路径自己的 `a:ln` 上（headEnd/tailEnd）。设计依据：docs/08 §6 —— 折线必须是**一条**可描边的
+ * 开放路径，否则两端箭头无从挂载（N 条独立直线只有首尾两条能挂，中间接缝还会露白）。
+ *
+ * 坐标：路径用抽象单位 0..100000，`a:path w/h` 与 `a:ext` 同比例 ⇒ DrawingML 线性映射回包围盒；
+ * 映射方向与 `a:ext` 空间一致（y 向下），不做翻转。导出后由 polylineEndsFromXml() 从写出的 XML **反推**验证。
+ *
+ * 为什么**不复用** custGeomXml()：那条码路是 `shape.kind === 'custGeom'` 的产物（`fill` + `ln` 跟在几何之后），
+ * 形状语义允许填色；折线必须"无填充 + 描边"，且改动既有 custGeom 写盘器会破坏"老工程产物逐字节不变"。
+ *
+ * 降级：若实测 PowerPoint 打开/渲染有问题，把 POLYLINE_MODE 改为 'segments' ⇒ N 条相邻重叠 1px 的直线
+ * （箭头只挂首尾两条；中段接缝靠 1px 重叠遮住）。降级必须记录理由并进 parity（polyLinesExp/Out 照数）。
+ */
+const POLYLINE_MODE = 'openPath' // 'openPath' | 'segments'
+const POLY_OVERLAP = 1 // 降级模式：相邻段端点**重叠** 1px（消接缝）
+
+function openPathXml(points) {
+  const xs = points.map((p) => Number(p[0]))
+  const ys = points.map((p) => Number(p[1]))
+  const x = Math.min(...xs)
+  const y = Math.min(...ys)
+  // 退化（全同点/纯水平/纯垂直）：至少 1px 包围盒，避免 w/h=0 的路径 Space 除零
+  const w = Math.max(1, Math.max(...xs) - x)
+  const h = Math.max(1, Math.max(...ys) - y)
+  const px = (v) => Math.round(((v - x) / w) * 100000)
+  const py = (v) => Math.round(((v - y) / h) * 100000)
+  const cmds = points.map((p, i) => `<a:${i === 0 ? 'moveTo' : 'lnTo'}><a:pt x="${px(p[0])}" y="${py(p[1])}"/></a:${i === 0 ? 'moveTo' : 'lnTo'}>`).join('')
+  return '<a:custGeom><a:avLst/><a:gdLst/><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/>'
+    + `<a:pathLst><a:path w="100000" h="100000" fill="none">${cmds}</a:path></a:pathLst></a:custGeom>`
 }
 
+function polylineSp(el, proof, arrowProof, warnField) {
+  const id = nid()
+  const pts = el.points.map((p) => [Number(p[0]), Number(p[1])])
+  if (pts.length < 2 || pts.some((p) => !Number.isFinite(p[0]) || !Number.isFinite(p[1]))) {
+    if (warnField) warnField(el.id, `points 不足 2 点或含非有限数值（${JSON.stringify(el.points)}）⇒ 按 1×1 退化点导出，不产坏 XML`)
+    pts.length = 0
+    pts.push([0, 0], [0, 0])
+  }
+  const arrow = arrowState(el.arrow)
+  validateLineFields(el, warnField)
+  const xs = pts.map((p) => p[0])
+  const ys = pts.map((p) => p[1])
+  const x = Math.min(...xs)
+  const y = Math.min(...ys)
+  const w = Math.max(...xs) - x
+  const h = Math.max(...ys) - y
+  // 箭头端计数（parity 用）：每条 'both' 线声明 1 个头端；'end'/true 只声明尾端。
+  if (arrow === 'both') arrowProof.headExp++
+
+  if (POLYLINE_MODE === 'segments') {
+    // 降级形态：N 条直线（straightConnector1），相邻端点重叠 POLY_OVERLAP px 去缝。
+    // 箭头挂首段的 headEnd / 末段的 tailEnd ⇒ 仍满足"两端箭头"。
+    const segs = []
+    for (let i = 0; i + 1 < pts.length; i++) {
+      const a = pts[i]
+      let b = pts[i + 1]
+      if (i + 1 < pts.length - 1) {
+        const dx = b[0] - a[0]
+        const dy = b[1] - a[1]
+        const len = Math.hypot(dx, dy) || 1
+        b = [b[0] + (dx / len) * POLY_OVERLAP, b[1] + (dy / len) * POLY_OVERLAP]
+      }
+      const first = i === 0
+      const last = i === pts.length - 2
+      const segArrow = first && last ? arrow : first && arrow === 'both' ? 'end' : last ? arrow : 'none'
+      segs.push(connectorSp({
+        id: first ? el.id : `${el.id}~s${i}`,
+        points: [a, b],
+        line: el.line,
+        arrow: segArrow === 'both' ? false : segArrow,
+      }))
+    }
+    if (proof) {
+      proof.out++
+      // 降级形态的几何自证：段链首尾必须仍落在源 points 的首尾上（用直连两端核对）
+      const back = connectorEndsFromXml(segs[0])
+      const back2 = connectorEndsFromXml(segs[segs.length - 1])
+      const same = back !== null && back2 !== null &&
+        Math.abs(back[0][0] - pts[0][0]) < 0.01 && Math.abs(back[0][1] - pts[0][1]) < 0.01 &&
+        Math.abs(back2[1][0] - pts[pts.length - 1][0]) < 0.01 && Math.abs(back2[1][1] - pts[pts.length - 1][1]) < 0.01
+      if (!same) proof.wrong.push(`${el.id}: 降级 N 段直线的首段起点/末段终点与源 points 不一致（${JSON.stringify(pts)}）`)
+    }
+    return segs.join('')
+  }
+
+  // 首选形态：单条开放路径（a:custGeom）
+  const xml = '<p:sp><p:nvSpPr><p:cNvPr id="' + id + '" name="' + xm(el.id) + '"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr>'
+    + '<p:spPr>' + xfrm(x, y, w, h) + openPathXml(pts) + '<a:noFill/>' + lineSpPr(el.line, el.arrow) + '</p:spPr>'
+    + '<p:txBody><a:bodyPr/><a:lstStyle/><a:p/></p:txBody></p:sp>'
+  if (proof) {
+    proof.out++
+    const back = polylineEndsFromXml(xml, w, h)
+    const same = back !== null && back.length === pts.length && back.every((p, i) =>
+      Math.abs(p[0] - pts[i][0]) < 0.01 && Math.abs(p[1] - pts[i][1]) < 0.01)
+    if (!same) {
+      proof.wrong.push(`${el.id}: 源 points ${JSON.stringify(pts.map((p) => p.map((v) => Math.round(v * 100) / 100)))} → OOXML 开放路径反推 ${back === null ? '解析失败' : JSON.stringify(back.map((p) => p.map((v) => Math.round(v * 100) / 100)))}`)
+    }
+  }
+  return xml
+}
+
+/**
+ * 从折线 XML 反推页面坐标顶点（导出自证；也供测试复用）。
+ * 语义：路径单位 0..pathW/pathH 经 `a:path w/h` → `a:ext cx/cy` 线性映射回包围盒，与 `a:ext` 同向（不做翻转）。
+ */
+export function polylineEndsFromXml(xml, w, h) {
+  const off = xml.match(/<a:off x="(-?\d+)" y="(-?\d+)"\/>/)
+  const ext = xml.match(/<a:ext cx="(\d+)" cy="(\d+)"\/>/)
+  const path = xml.match(/<a:path w="(\d+)" h="(\d+)"[^>]*>([\s\S]*?)<\/a:path>/)
+  if (!off || !ext || !path) return null
+  const x = Number(off[1]) / EMU
+  const y = Number(off[2]) / EMU
+  const cx = Number(ext[1]) / EMU
+  const cy = Number(ext[2]) / EMU
+  const pw = Number(path[1])
+  const ph = Number(path[2])
+  if (!(pw > 0) || !(ph > 0)) return null
+  // w/h 由调用方给出时用于把 pt 归一映射；缺省则用 a:ext（两者一致）
+  const outW = typeof w === 'number' ? w : cx
+  const outH = typeof h === 'number' ? h : cy
+  const pts = []
+  for (const m of path[3].matchAll(/<a:(moveTo|lnTo)><a:pt x="(-?\d+)" y="(-?\d+)"\/><\/a:(?:moveTo|lnTo)>/g)) {
+    if (m[1] === 'moveTo' && pts.length > 0) break
+    pts.push([x + (Number(m[2]) / pw) * outW, y + (Number(m[3]) / ph) * outH])
+  }
+  return pts.length ? pts : null
+}
+
+
 // ── text ─────────────────────────────────────────────────────────────────
 const FIT_TOL = 1 // 与 verify 的 TOL 一致：verify 通过 ⇒ 导出不缩字（反馈 E2 ★★）
 
@@ -484,9 +731,13 @@ function srgbClrXml(color, alpha) {
  *   p2 在 p1 左侧 → flipH；p2 在 p1 上方 → flipV。
  * 漏写会镜像斜率；两条交叉线（如 × 的两笔）还会重叠成一条 —— 预览对、PowerPoint 里不对的根源。
  * `tailEnd`（箭头）始终落在画出的"终点"＝ p2，所以定点翻转后箭头方向自动正确。
+ * 阶段 A：`arrow: 'both'` 时额外写 headEnd（落在**起点** p1 侧）；字段值经 validateLineFields 复核（非法值降级 + 告警）。
+ * **2 点 + arrow: true + 无 dash 的产物与改动前逐字节一致**（dash 缺省不写元素、true ≡ 'end'）——回归硬门槛。
  */
-function connectorSp(el, proof) {
+function connectorSp(el, proof, arrowProof, warnField) {
   const id = nid()
+  validateLineFields(el, warnField)
+  if (arrowProof && arrowState(el.arrow) === 'both') arrowProof.headExp++
   const p1 = el.points[0]
   const p2 = el.points[1]
   const x1 = p1[0]
@@ -504,7 +755,7 @@ function connectorSp(el, proof) {
   const flips = (x2 < x1 ? ' flipH="1"' : '') + (y2 < y1 ? ' flipV="1"' : '')
   const xml = '<p:cxnSp><p:nvCxnSpPr><p:cNvPr id="' + id + '" name="' + xm(el.id) + '"/><p:cNvCxnSpPr/><p:nvPr/></p:nvCxnSpPr>'
     + '<p:spPr>' + xfrm(minX, minY, wdt, hgt, 0, flips) + '<a:prstGeom prst="straightConnector1"><a:avLst/></a:prstGeom>'
-    + lineSpPr(el.line, el.arrow === true) + '</p:spPr></p:cxnSp>'
+    + lineSpPr(el.line, el.arrow === true || el.arrow === 'end' ? true : el.arrow === 'both' ? 'both' : false) + '</p:spPr></p:cxnSp>'
   if (proof !== undefined && proof !== null) {
     proof.out++
     // 从写出的 XML 反推线段两端（OOXML 语义：本地 (0,0)→(w,h) 经 flip 映射回页面），必须与源 points 一致。
@@ -513,9 +764,13 @@ function connectorSp(el, proof) {
       Math.abs(back[0][0] - x1) < 0.01 && Math.abs(back[1][0] - x2) < 0.01 &&
       Math.abs(back[0][1] - y1) < 0.01 && Math.abs(back[1][1] - y2) < 0.01
     if (!same) proof.wrong.push(`${el.id}: 源 [[${x1},${y1}],[${x2},${y2}]] → OOXML 还原 ${back === null ? '解析失败' : JSON.stringify(back.map((p) => p.map((v) => Math.round(v * 100) / 100)))}`)
-    // 箭头必须在 <a:ln> 内部（写在外面 PowerPoint 直接忽略）
-    if (el.arrow === true && !/<a:ln\b[^>]*>(?:(?!<\/a:ln>)[\s\S])*<a:tailEnd/.test(xml)) {
-      proof.wrong.push(`${el.id}: arrow=true 但 <a:tailEnd> 不在 <a:ln> 内（PowerPoint 会忽略箭头）`)
+    // 箭头必须在 <a:ln> 内部（写在外面 PowerPoint 直接忽略）；两端箭头必须两端都在。
+    const a = arrowState(el.arrow)
+    if (a !== 'none' && !/<a:ln\b[^>]*>(?:(?!<\/a:ln>)[\s\S])*<a:tailEnd/.test(xml)) {
+      proof.wrong.push(`${el.id}: arrow=${JSON.stringify(el.arrow)} 但 <a:tailEnd> 不在 <a:ln> 内（PowerPoint 会忽略箭头）`)
+    }
+    if (a === 'both' && !/<a:ln\b[^>]*>(?:(?!<\/a:ln>)[\s\S])*<a:headEnd/.test(xml)) {
+      proof.wrong.push(`${el.id}: arrow='both' 但 <a:headEnd> 不在 <a:ln> 内`)
     }
   }
   return xml

package/lib/pptd/layout.js

@@ -131,10 +131,18 @@ function boundsOf(el) {
   return { x, y, w: Math.max(1, Math.max(...xs) - x), h: Math.max(1, Math.max(...ys) - y) }
 }
 
+// 阶段 A-④：`attach`（把线段两端锚到元素边）在归一化阶段解析成坐标。
+// 方向是 layout → relations（relations 不依赖 layout），无循环依赖。
+import { resolveAttach } from './relations.js'
+// G1：手画与族共用同一份路由后处理（正交化 + 箭头端最短直段），带 n<3 与折返两道守卫
+import { routePolyline } from './route-geometry.js'
+
 /** 归一化一个页面：元素 → 统一对象（含解析样式与文本度量）。 */
 export function normalizePage(page, ctx) {
   const { resolveColor, styleOf } = ctx
   const elements = []
+  // attach 解析要用**原始 DSL 元素**的几何查 ref（此时还没归一化）
+  const srcById = new Map((page.page.elements ?? []).map((e) => [e.elementId, e]))
   for (const el of page.page.elements ?? []) {
     const b = boundsOf(el)
     const base = {
@@ -142,6 +150,11 @@ export function normalizePage(page, ctx) {
       type: el.elementType,
       bounds: b,
       ...(el.role ? { role: el.role } : {}),
+      // 阶段 A（docs/08 §1）：结构声明字段必须**透传**——归一化是白名单式构造，
+      // 漏在这里会让"结构关系"在导出/校验层凭空消失（几何反验证在 src/pptd/relations.js）。
+      ...(el.contains ? { contains: el.contains } : {}),
+      ...(el.badgeOf ? { badgeOf: el.badgeOf } : {}),
+      ...(el.roleReason ? { roleReason: el.roleReason } : {}),
     }
     switch (el.elementType) {
       case 'text': {
@@ -161,9 +174,23 @@ export function normalizePage(page, ctx) {
         break
       }
       case 'line': {
-        const pts = el.points ? el.points.map((p) => p) : [[el.x1, el.y1], [el.x2, el.y2]]
-        const line = { color: resolveColor(el.line?.color ?? '#000'), width: el.line?.width ?? 1 }
-        elements.push({ ...base, type: 'line', points: pts, arrow: !!el.arrow, line })
+        // 阶段 A-④：`attach` **优先于**手写 points —— 解析成坐标，被改写的端点进 attachNotes（另行提示，不静默覆盖）。
+        // 导出侧只认 points（保持纯写盘层）；几何仍由 relations 的反验证兜底。
+        const resolved = el.attach ? resolveAttach(el, srcById) : null
+        const raw = resolved?.points ?? (el.points ? el.points.map((p) => p) : [[el.x1, el.y1], [el.x2, el.y2]])
+        //   复用 route-geometry.js 的同一实现（族与手画不再双标），守卫详情见该模块注释。
+        //   例外与族一致：斜段图形（环/放射语义）豁免正交化；亦可显式写 orthogonal: false。
+        const exempt = el.orthogonal === false || el.line?.orthogonal === false
+          || el.role === 'decoration' || Boolean(el.roleReason)
+        const pts = exempt ? raw : routePolyline(raw, el.arrow ?? false)
+        const line = { color: resolveColor(el.line?.color ?? '#000'), width: el.line?.width ?? 1, ...(el.line?.dash ? { dash: el.line.dash } : {}) }
+        // 阶段 A：`arrow` 必须**原样**透传。原先写作 `!!el.arrow` 会把 `'both'` 压成 `true`
+        // ⇒ 两端箭头/虚线折线走到导出层时已经不认得（本轮实测：headEnd 计数 0）。
+        elements.push({
+          ...base, type: 'line', points: pts, arrow: el.arrow ?? false, line,
+          ...(el.attach ? { attach: el.attach } : {}),
+          ...(resolved?.notes?.length ? { attachNotes: resolved.notes } : {}),
+        })
         break
       }
       case 'image':
@@ -205,5 +232,29 @@ export function normalizePage(page, ctx) {
         elements.push(base)
     }
   }
+  // ── 兜底规整：去除折线"折返尖刺"（X1 最终修复）──────────────────────────
+  // 用户实测（图 10 顶端多出一根线）：锚点解析/后处理之后，点序里会出现"共线且折返"的多余点
+  //（如 91.1 → 73.1 → 118.1），画出来就是一根戳出去的线。
+  // 放在 **normalizePage 末尾** 是因为：预览、导出、门禁**都**走本函数 ⇒ 这是唯一
+  // "改完不会被任何后续步骤覆盖"的位置（此前我改在它的上游，被解析/后处理覆盖 ⇒ 修不掉）。
+  for (const e of elements) {
+    if (e.type !== 'line' || !Array.isArray(e.points) || e.points.length < 3) continue
+    const res = []
+    for (const q of e.points) {
+      // 反复回退，直到"最后两点 + 当前点"不再折返；**当前点始终保留**
+      //（第一版写成 pop 后 continue，把当前点一起丢了 ⇒ 3 点被规整成 1 点 ⇒ 渲染报 "p2 is not iterable"，实测踩过）
+      while (res.length >= 2) {
+        const a1 = res[res.length - 2]
+        const b1 = res[res.length - 1]
+        const sameX = Math.abs(a1[0] - b1[0]) < 0.5 && Math.abs(b1[0] - q[0]) < 0.5
+        const sameY = Math.abs(a1[1] - b1[1]) < 0.5 && Math.abs(b1[1] - q[1]) < 0.5
+        const reversal = (sameX && (b1[1] - a1[1]) * (q[1] - b1[1]) < 0) || (sameY && (b1[0] - a1[0]) * (q[0] - b1[0]) < 0)
+        if (reversal) res.pop()
+        else break
+      }
+      res.push(q)
+    }
+    if (res.length >= 2) e.points = res
+  }
   return elements
 }