w-flowchart 1.0.0 → 1.0.2

package/package.json

@@ -1,49 +1,52 @@
-{
-  "name": "w-flowchart",
-  "version": "1.0.0",
-  "main": "dist/w-flowchart.umd.js",
-  "dependencies": {
-    "@antv/g6": "^5.1.1",
-    "@dagrejs/dagre": "^1.1.8",
-    "@joint/core": "^4.3.0",
-    "@logicflow/core": "^2.2.4",
-    "@mermaid-js/layout-elk": "^0.2.2",
-    "@terrastruct/d2": "0.1.33",
-    "@xyflow/react": "^12.11.2",
-    "cytoscape": "^3.34.0",
-    "cytoscape-dagre": "^4.0.0",
-    "dagre": "^0.8.5",
-    "elkjs": "^0.11.1",
-    "graphre": "^0.1.3",
-    "lodash-es": "^4.18.1",
-    "mermaid10": "npm:mermaid@^10.9.6",
-    "mermaid11": "npm:mermaid@^11.16.0",
-    "nomnoml": "^1.7.0",
-    "playwright": "^1.61.1",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "sharp": "0.35.3",
-    "wsemi": "^1.8.64"
-  },
-  "devDependencies": {
-    "pixelmatch": "^7.2.0",
-    "pngjs": "^7.0.0",
-    "w-package-tools": "^1.1.10"
-  },
-  "scripts": {
-    "test": "mocha --parallel --timeout 60000",
-    "deploy": "gh-pages -d docs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yuda-lyu/w-flowchart.git"
-  },
-  "keywords": [
-    "package",
-    "tool",
-    "flowchart",
-    "nodejs"
-  ],
-  "author": "yuda-lyu(semisphere)",
-  "license": "MIT"
-}
+{
+  "name": "w-flowchart",
+  "version": "1.0.2",
+  "main": "dist/w-flowchart.umd.js",
+  "dependencies": {
+    "@antv/g-lite": "^2.7.0",
+    "@antv/g-svg": "^2.1.1",
+    "@antv/g6": "^5.1.1",
+    "@dagrejs/dagre": "^1.1.8",
+    "@joint/core": "^4.3.0",
+    "@logicflow/core": "^2.2.4",
+    "@mermaid-js/layout-elk": "^0.2.2",
+    "@terrastruct/d2": "0.1.33",
+    "@xyflow/react": "^12.11.2",
+    "cytoscape": "^3.34.0",
+    "cytoscape-dagre": "^4.0.0",
+    "cytoscape-svg": "^0.4.0",
+    "dagre": "^0.8.5",
+    "elkjs": "^0.11.1",
+    "graphre": "^0.1.3",
+    "lodash-es": "^4.18.1",
+    "mermaid10": "npm:mermaid@^10.9.6",
+    "mermaid11": "npm:mermaid@^11.16.0",
+    "nomnoml": "^1.7.0",
+    "playwright": "^1.61.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "sharp": "0.35.3",
+    "wsemi": "^1.8.64"
+  },
+  "devDependencies": {
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
+    "w-package-tools": "^1.1.10"
+  },
+  "scripts": {
+    "test": "mocha --parallel --timeout 60000",
+    "deploy": "gh-pages -d docs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuda-lyu/w-flowchart.git"
+  },
+  "keywords": [
+    "package",
+    "tool",
+    "flowchart",
+    "nodejs"
+  ],
+  "author": "yuda-lyu(semisphere)",
+  "license": "MIT"
+}

package/src/WFlowchart.mjs

@@ -0,0 +1,97 @@
+// WFlowchart — 統一產圖入口: 輸入正規化繪圖數據 inp, 產出 PNG 圖
+//   inp: 正規化繪圖數據 { dir, nodes, edges }(與繪圖庫無關, 結構同 test/data/*.json; cls 見 common/palette.mjs)
+//   opt.mode: 'p1'~'p10', 各對應一套產線(繪圖引擎與佈局各異, 見各 pN/gen.mjs 檔頭說明), 預設 'p10'
+//     p1: mermaid(dagre)   p2: mermaid(ELK)     p3: nomnoml         p4: cytoscape(dagre)
+//     p5: D2               p6: G6(antv-dagre)   p7: JointJS(dagre)  p8: LogicFlow(dagre)
+//     p9: dagre 自寫渲染    p10: ELK 自寫渲染
+//   回傳: Promise<Buffer>(PNG)
+import get from 'lodash-es/get.js'
+import cloneDeep from 'lodash-es/cloneDeep.js'
+import isestr from 'wsemi/src/isestr.mjs'
+import iseobj from 'wsemi/src/iseobj.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import isarr from 'wsemi/src/isarr.mjs'
+import { deriveLabels } from './common/derive.mjs'
+
+// 引擎延遲載入: 各產線依 opt.mode 動態 import(), 使用者只為所選產線付出依賴成本
+//   (各 pN 模組層即讀取其繪圖庫 bundle 檔; p5 另載入 @terrastruct/d2 與 sharp, 其上游缺陷不影響其他產線)
+const LOADERS = {
+    p1: () => import('./p1/gen.mjs'),
+    p2: () => import('./p2/gen.mjs'),
+    p3: () => import('./p3/gen.mjs'),
+    p4: () => import('./p4/gen.mjs'),
+    p5: () => import('./p5/gen.mjs'),
+    p6: () => import('./p6/gen.mjs'),
+    p7: () => import('./p7/gen.mjs'),
+    p8: () => import('./p8/gen.mjs'),
+    p9: () => import('./p9/gen.mjs'),
+    p10: () => import('./p10/gen.mjs'),
+}
+
+// svg 輸出: p1/p2/p3/p5/p10 引擎原生輸出 SVG 字串; p7/p8 為 SVG DOM 序列化(樣式已內嵌);
+//   p4 經 cytoscape-svg 外掛、p6 經 @antv/g-svg renderer 重繪為 SVG(皆經像素級忠實度驗證);
+//   p9 節點為 React Flow 之 HTML DOM, 無忠實 SVG 可產 → 不支援
+const SVG_MODES = ['p1', 'p2', 'p3', 'p4', 'p5', 'p6', 'p7', 'p8', 'p10']
+
+/**
+ * 產製流程圖 PNG
+ *
+ * @param {Object} inp 輸入正規化繪圖數據物件,格式 { dir, nodes, edges },與繪圖引擎無關
+ * @param {String} [inp.dir='TB'] 輸入佈局方向字串,可選 'TB'(上而下)或 'LR'(左而右),預設 'TB'
+ * @param {Array} inp.nodes 輸入節點陣列,每項為一般節點 { id, label, cls, group? } 或富節點 { id, title, items, cls, group? };cls 為色票鍵(見 src/common/palette.mjs),結尾 G/G2 者為群組容器,group 為所屬容器 id(容器可巢狀)
+ * @param {Array} inp.edges 輸入邊陣列,每項為 { from, to, label?, kind? },kind 給 'dashed' 為虛線
+ * @param {Object} [opt={}] 輸入設定物件,原樣傳遞給產線,預設 {}
+ * @param {String} [opt.mode='p10'] 輸入產線模式字串,可選 'p1'~'p10',各對應一套繪圖引擎產線(技術概念見各 src/pN/README.md),未指定或非有效字串時預設 'p10'
+ * @param {String} [opt.output='png'] 輸入輸出格式字串,可選 'png'(回傳 PNG Buffer)或 'svg'(回傳 standalone SVG 字串),未指定或非有效字串時預設 'png';svg 支援 p1~p8 與 p10,p9(React Flow 之 HTML DOM 渲染)不支援,給 svg 會拋錯
+ * @returns {Promise} 回傳 Promise,resolve 依 opt.output 回傳 PNG 圖之 Buffer 或 SVG 字串,reject 回傳錯誤訊息
+ * @example
+ *
+ * import fs from 'fs'
+ * import WFlowchart from 'w-flowchart'
+ *
+ * let inp = {
+ *     dir: 'TB',
+ *     nodes: [
+ *         { id: 'A', label: '開始', cls: 'blue' },
+ *         { id: 'G', label: '處理群組', cls: 'greenG' },
+ *         { id: 'B', label: '步驟一', cls: 'green', group: 'G' },
+ *         { id: 'C', title: '服務', items: ['項目一', '項目二'], cls: 'green', group: 'G' },
+ *         { id: 'D', label: '判斷?', cls: 'diamond' },
+ *         { id: 'E', label: '結束', cls: 'orange' },
+ *     ],
+ *     edges: [
+ *         { from: 'A', to: 'B' },
+ *         { from: 'B', to: 'C', label: '呼叫' },
+ *         { from: 'C', to: 'D' },
+ *         { from: 'D', to: 'E', label: '通過' },
+ *         { from: 'D', to: 'B', kind: 'dashed', label: '退回' },
+ *     ],
+ * }
+ *
+ * let buf = await WFlowchart(inp) //預設 mode 'p10'; 可用 WFlowchart(inp, { mode: 'p3' }) 指定產線
+ * fs.writeFileSync('flowchart.png', buf)
+ * // => 產出 flowchart.png
+ *
+ * let svg = await WFlowchart(inp, { output: 'svg' }) //輸出 standalone SVG 字串(p9 不支援)
+ * fs.writeFileSync('flowchart.svg', svg)
+ * // => 產出 flowchart.svg
+ */
+async function WFlowchart(inp, opt = {}) {
+    let mode = get(opt, 'mode')
+    if (!isestr(mode)) mode = 'p10' //未指定或非有效字串時預設 p10
+    const m = mode.trim().toLowerCase()
+    if (!LOADERS[m]) throw new Error(`invalid opt.mode[${mode}], 須為 ${Object.keys(LOADERS).join(', ')} 之一`)
+    let output = get(opt, 'output')
+    if (!isestr(output)) output = 'png' //未指定或非有效字串時預設 png
+    const o = output.trim().toLowerCase()
+    if (o !== 'png' && o !== 'svg') throw new Error(`invalid opt.output[${output}], 須為 png 或 svg`)
+    if (o === 'svg' && !SVG_MODES.includes(m)) throw new Error(`mode[${m}] 不支援 svg 輸出, 支援: ${SVG_MODES.join(', ')}`)
+    if (!iseobj(inp)) throw new Error('invalid inp, 須為 { dir, nodes, edges } 正規化繪圖數據')
+    if (!isearr(inp.nodes)) throw new Error('invalid inp.nodes, 須為非空陣列')
+    if (!isarr(inp.edges)) throw new Error('invalid inp.edges, 須為陣列')
+    const data = deriveLabels(cloneDeep(inp)) //deriveLabels 會就地改動, 先複製避免污染 caller 之 inp
+    const gen = await LOADERS[m]() //檢核全過才載入所選產線引擎(延遲載入)
+    return await (o === 'svg' ? gen.genSvg : gen.genPng)(data, opt)
+}
+
+export default WFlowchart

package/src/p1/README.md

@@ -3,7 +3,7 @@
 ## 技術核心
 
 - **繪圖庫**: mermaid 第 10 版系列（package.json 以 npm alias `mermaid10` 安裝，與 p2 之第 11 版系列並存），透過 `common/pkg.mjs` 的 `pkgScript('mermaid10/dist/mermaid.min.js')` 讀取本機 `node_modules` 內容並內聯注入 `<script>` 標籤，於 Playwright 開啟的 Chromium 頁面內執行；不經 CDN，斷網環境亦可運作。
-- **渲染方式**: `genFig()` 為每張圖建立獨立的 Playwright `page`（`browser.newPage()`），避免 mermaid 內部 render id 衝突。將 `mermaidHtml()` 產生的 HTML 字串以 `page.setContent()` 注入，等待 `document.title === 'DONE'` 確認渲染完成（或 `FAIL` 時拋出錯誤），再以 `page.waitForFunction` 超時 30 秒防呆。
+- **渲染方式**: 內部 `renderFigPage()` 為每次渲染建立獨立的 Playwright `page`（`browser.newPage()`），避免 mermaid 內部 render id 衝突。將 `mermaidHtml()` 產生的 HTML 字串以 `page.setContent()` 注入，等待 `document.title === 'DONE'` 確認渲染完成（或 `FAIL` 時拋出錯誤），再以 `page.waitForFunction` 超時 30 秒防呆。
 - **截圖目標**: `page.locator('#box svg').screenshot()`，只截 SVG 元素本身，不含外層 `div#box` 的 padding 背景。
 - **解析度**: `deviceScaleFactor: 4`，Chromium 以 4 倍畫素密度渲染 SVG 向量圖，輸出 PNG 清晰度極高，適合印刷品質報告。
 - **字型**: HTML `<body>` 及 mermaid `themeVariables.fontFamily` 均指定 `'微軟正黑體','Microsoft JhengHei',sans-serif`；截圖前以 `page.evaluate(() => document.fonts.ready)` 確保字型載入完成。
@@ -44,7 +44,7 @@
 
 ### 對外介面
 
-- 產線唯一輸出入口為 `genPng(data, opt)`，`data` 為正規化繪圖數據 `{ dir, nodes, edges }`，回傳 `Promise<Buffer>`（PNG）；`genPng` 自帶瀏覽器生命週期（`chromium.launch()` → 渲染 → `browser.close()`），呼叫端不需自行管理 Playwright。
+- 產線對外介面為 `genPng(data, opt)` 與 `genSvg(data, opt)`，`data` 為正規化繪圖數據 `{ dir, nodes, edges }`；`genPng` 回傳 `Promise<Buffer>`（PNG），`genSvg` 回傳 standalone SVG 字串（引擎原生輸出、依 viewBox 寫死寬高、`&nbsp;` 正規化為 `&#160;`）；兩者皆自帶瀏覽器生命週期（`chromium.launch()` → 渲染 → `browser.close()`），呼叫端不需自行管理 Playwright。
 - 統一由 `src/WFlowchart.mjs` 依 `mode === 'p1'` 呼叫，不提供批次流程或落地寫檔行為，是否寫檔、寫至何處由呼叫端決定。
 
 ## 自動化機制

package/src/p1/gen.mjs

@@ -8,11 +8,11 @@ import { pkgScript } from '../common/pkg.mjs'
 // mermaid@10 由本機 node_modules 內聯注入(取代 CDN, 斷網環境可用)
 const MERMAID_JS = pkgScript('mermaid10/dist/mermaid.min.js')
 
-// 把標準節點 label 轉成 mermaid 節點形狀語法
+// 把標準節點 label 轉成 mermaid 節點形狀語法(id 經 qid 消歧)
 //   diamond → {label}  / 其餘 → ["label"]
-function nodeShape(nd) {
-    if (nd.cls === 'diamond') return `${nd.id}{"${nd.label}"}`
-    return `${nd.id}["${nd.label}"]`
+function nodeShape(nd, qid) {
+    if (nd.cls === 'diamond') return `${qid(nd.id)}{"${nd.label}"}`
+    return `${qid(nd.id)}["${nd.label}"]`
 }
 
 // 正規化數據 → mermaid flowchart DSL 字串
@@ -27,6 +27,20 @@ function nodeShape(nd) {
 function translate(data) {
     const { dir, nodes, edges } = data
 
+    // mermaid 保留字(end/click/style/class/subgraph/direction 等)不可作節點 id → 一律加前綴消歧
+    //   僅影響 DSL 內部識別(顯示文字仍用 label); 不同原 id 淨化後若同名, 以序號區隔避免節點被合併
+    const used = new Set()
+    const qidMap = {}
+    const qid = (id) => {
+        if (qidMap[id]) return qidMap[id]
+        const base = 'n_' + String(id).replace(/[^A-Za-z0-9_]/g, '_')
+        let q = base, k = 2
+        while (used.has(q)) q = base + '_' + (k++)
+        used.add(q)
+        qidMap[id] = q
+        return q
+    }
+
     // 索引: id → node
     const byId = {}
     for (const nd of nodes) byId[nd.id] = nd
@@ -59,7 +73,7 @@ function translate(data) {
     }
     const classLines = []
     for (const [cls, ids] of Object.entries(clsToIds)) {
-        classLines.push(`  class ${ids.join(',')} ${cls}`)
+        classLines.push(`  class ${ids.map(qid).join(',')} ${cls}`)
     }
 
     // 拓樸: 哪些節點直接屬於哪個容器(含巢狀)
@@ -73,11 +87,11 @@ function translate(data) {
     function renderSubgraph(gid, indent) {
         const g = byId[gid]
         const lines = []
-        lines.push(`${indent}subgraph ${gid}["${g.label}"]`)
+        lines.push(`${indent}subgraph ${qid(gid)}["${g.label}"]`)
         // 直接子節點(非容器)
         const directChildren = nodes.filter(nd => nd.group === gid && !isGroupCls(nd.cls))
         for (const nd of directChildren) {
-            lines.push(`${indent}  ${nodeShape(nd)}`)
+            lines.push(`${indent}  ${nodeShape(nd, qid)}`)
         }
         // 巢狀容器(容器的 group === gid)
         const nestedGroups = nodes.filter(nd => isGroupCls(nd.cls) && nd.group === gid)
@@ -93,14 +107,14 @@ function translate(data) {
     for (const ed of edges) {
         const arrow = ed.kind === 'dashed' ? '-..->' : '-->'
         const lbl = ed.label ? `|"${ed.label}"| ` : ''
-        edgeLines.push(`  ${ed.from} ${arrow} ${lbl}${ed.to}`)
+        edgeLines.push(`  ${qid(ed.from)} ${arrow} ${lbl}${qid(ed.to)}`)
     }
 
     // 組裝 DSL
     const lines = [`flowchart ${dir}`]
     // 1. 獨立節點
     for (const nd of standaloneNodes) {
-        lines.push(`  ${nodeShape(nd)}`)
+        lines.push(`  ${nodeShape(nd, qid)}`)
     }
     // 2. 頂層 subgraph
     for (const gid of topGroupIds) {
@@ -169,35 +183,55 @@ mermaid.initialize({ startOnLoad:false, theme:'base', themeVariables:{ fontFamil
 </script></body></html>`
 }
 
-// 單張渲染: 每張用新 page(避免 mermaid render id 衝突), deviceScaleFactor:4(向量圖放大提高清晰度)
-//   fpOut 省略時不寫檔; 皆回傳 PNG Buffer
-async function genFig(browser, code, fpOut) {
-    const page = await browser.newPage({ deviceScaleFactor: 4 })
+// 渲染單張至就緒頁面(mermaid DONE + 字型就緒), deviceScaleFactor:4(向量圖放大提高清晰度); caller 負責 close browser
+async function renderFigPage(code) {
+    const browser = await chromium.launch()
     try {
+        const page = await browser.newPage({ deviceScaleFactor: 4 })
         await page.setContent(mermaidHtml(code), { waitUntil: 'load' })
         await page.waitForFunction(() => document.title === 'DONE' || document.title === 'FAIL', { timeout: 30000 })
         const title = await page.title()
         if (title !== 'DONE') {
             const msg = await page.evaluate(() => { const el = document.getElementById('box'); return el ? el.innerText : '' })
-            throw new Error(`mermaid render failed for ${fpOut || '(buffer)'}: ${msg}`)
+            throw new Error(`mermaid render failed: ${msg}`)
         }
         await page.evaluate(() => document.fonts.ready)
-        return await page.locator('#box svg').screenshot(fpOut ? { path: fpOut } : {})
+        return { browser, page }
     }
-    finally {
-        await page.close()
+    catch (err) {
+        await browser.close()
+        throw err
     }
 }
 
 // 單張渲染 → PNG Buffer(供 WFlowchart 統一入口呼叫; 自帶瀏覽器生命週期)
 async function genPng(data, opt = {}) {
-    const browser = await chromium.launch()
+    const { browser, page } = await renderFigPage(translate(data))
+    try {
+        return await page.locator('#box svg').screenshot()
+    }
+    finally {
+        await browser.close()
+    }
+}
+
+// 單張渲染 → SVG 字串(#box 內後處理完成之 SVG; &nbsp; 正規化為 &#160; 使其為合法 standalone SVG)
+//   mermaid 之 svg 為響應式(width:100% + max-width), 脫離頁面尺寸會漂移 → 序列化前依 viewBox 寫死 width/height
+async function genSvg(data, opt = {}) {
+    const { browser, page } = await renderFigPage(translate(data))
     try {
-        return await genFig(browser, translate(data), null)
+        return (await page.evaluate(() => {
+            const el = document.querySelector('#box svg')
+            const vb = el.viewBox.baseVal
+            el.style.maxWidth = 'none'
+            el.setAttribute('width', Math.ceil(vb.width))
+            el.setAttribute('height', Math.ceil(vb.height))
+            return document.getElementById('box').innerHTML
+        })).replace(/&nbsp;/g, '&#160;').trim()
     }
     finally {
         await browser.close()
     }
 }
 
-export { genPng }
+export { genPng, genSvg }

package/src/p10/README.md

@@ -6,7 +6,7 @@ p1~p9 為現成繪圖套件;**p10 是唯一「自寫 SVG 渲染器」產線**:
 
 - **佈局引擎**:`elkjs`(Eclipse Layout Kernel 的 JS 版,`elk.bundled.js` UMD 主執行緒、免 worker),由本機 `node_modules` 讀出後於 `gen.mjs` 模組載入時以 `common/pkg.mjs` 的 `pkgScript` 內聯注入 `PAGE_HTML`(取代 CDN,斷網環境可用),於 Playwright headless 頁內執行。`new ELK().layout(graph)` 回傳各節點/容器之座標尺寸與各邊之 sections(轉折點)。
 - **渲染**:本產線**自行把 ELK 結果組成 SVG 字串**(rect / polygon 菱形 / path 折線 + 箭頭 / foreignObject 文字),插入頁面後對 `#stage svg` 截圖。`deviceScaleFactor:2`。中文以 `foreignObject` 內 div 渲染(瀏覽器原生量字、不爆框)。
-- **呼叫入口**:`export async function genPng(data, opt = {})` 為唯一對外介面,回傳 `Promise<Buffer>`(PNG);由 `src/WFlowchart.mjs` 之 `GENS.p10` 統一調用(`mode: 'p10'`)。`data` 為正規化繪圖數據 `{ dir, nodes, edges }`;`opt` 保留擴充,目前原樣接收但未使用。`gen.mjs` 另外 `export function translate` 與 `export const PAGE_HTML`,供 `test/`(19 案結構不變量 + 快照回歸測試)重用真實管線(不複製渲染器)。
+- **呼叫入口**:`export async function genPng(data, opt = {})` 與 `export async function genSvg(data, opt = {})` 為對外介面,`genPng` 回傳 `Promise<Buffer>`(PNG),`genSvg` 回傳本產線自組之 standalone SVG 字串(`#stage` 內容,`&nbsp;` 正規化為 `&#160;`);由 `src/WFlowchart.mjs` 之 `GENS.p10` 統一調用(`mode: 'p10'`)。`data` 為正規化繪圖數據 `{ dir, nodes, edges }`;`opt` 保留擴充,目前原樣接收但未使用。`gen.mjs` 另外 `export function translate` 與 `export const PAGE_HTML`,供 `test/`(結構不變量 + 快照回歸測試)重用真實管線(不複製渲染器)。
 
 ## 產製原理(資料驅動)
 
@@ -23,9 +23,13 @@ p1~p9 為現成繪圖套件;**p10 是唯一「自寫 SVG 渲染器」產線**:
 - **字型全覆蓋**:所有 SVG 文字(節點/容器標題/邊標籤)走 `foreignObject` + `font-family:Microsoft JhengHei`,無遺漏、不爆框。
 - **邊標籤白光暈**:邊標籤 div 以多向 `text-shadow` 白光暈(`EDGE.haloColor/haloWidth`),透明底、不遮線。
 - **菱形標籤置中**:菱形以 polygon 畫、標籤 foreignObject 置中於外接框,天然置中(優於 vis 需 vadjust 硬調)。
+- **菱形端點貼齊(共進共出)**:ELK 以外接矩形算邊端點,落在矩形邊上非頂點處會與菱形斜邊「空接」。依「側」(上/下/左/右)獨立處理:**出**→一律由該側「頂點」出發,多條共用首段後於各自高度 90 度轉出(分岔);**進**→該側無出時全部匯入「頂點」(各自橫移至中軸共用末段,箭頭重合),該側有出時依「半側」匯入該半側「斜邊中點」(頂點讓給出,進出不同點)。正交線交叉允許存在(正交路由常態),一致性優先。13 種進出組合由測試之單元驗證逐一把關(其中「同半側」類組合受 ELK 埠序限制,乾淨合成圖排不出,僅能在函式層驗證)。
+- **正交路徑化簡(碰撞偵測把關)**:ELK 階層邊(`INCLUDE_CHILDREN`)偶發「先繞反方向再折返」的 S/U 形繞行(跨容器回邊尤甚)。渲染前對每條路徑反覆嘗試把「平行-垂直-平行」三段窗收斂為兩段,僅在碰撞偵測全過才接受:不撞節點框/容器標題帶/邊標籤、不與他邊平行段貼齊併線;端點段軸向與方向不可翻轉(維持節點進出方向,先於菱形貼齊執行故不干擾其規則);邊標籤若因化簡脫離路徑則整段還原。已極簡之路徑零誤觸。
 - 版面間距為通用常數(`elk.spacing.*`),尺寸由內容自然決定,無逐圖魔術數字。
 
 ## 已知限制
 
-- **循環(回邊)起點**:ELK 的斷環點不一定讓「流程起點」落在最上(如作業流程的「退回」迴圈),屬版面取捨、非錯誤(可調 ELK cycle-breaking 選項)。
+- **循環(回邊)起點**:ELK 的斷環點不一定讓「流程起點」落在最上(如流程的「退回」迴圈),屬版面取捨、非錯誤(可調 ELK cycle-breaking 選項)。
 - **線性長鏈**:純線性流程(如批次)會被拉得較高(與 dagre 系一致)。
+- **A4 折排容器不可含內部循環**:被自動折排(`elk.aspectRatio` + `SINGLE_EDGE` wrapping)挑中的容器,若其內部邊集含循環,折排結果不穩定,部分節點數組合會令 elkjs 內部拋例外(`IndexOutOfBoundsException` / `NoSuchElementException`)。實測經驗法則:讓會被折排的容器內部保持無環、單一入出口,退回/重試循環放在該容器之外或小型巢狀子群組內。
+- **二層巢狀 + 密集帶標籤邊之組合**:巢狀子群組內有「4+ 節點直鏈且 3+ 連續帶標籤邊」,或「子群組內部帶標籤/分支邊 + 同深度姊妹群組間直連邊」之組合,部分情況會觸發 elkjs 內部例外。繞法:讓功能區群組各自獨立成鏈/分支,跨區以共用之獨立葉節點中繼,或改用群組↔群組邊。