w-flowchart 1.0.0 → 1.0.2

package/src/p5/gen.mjs

@@ -5,8 +5,8 @@
 //   注意：本版 D2(0.1.33 / WASM v0.7.0) 傳入自訂 font buffer 會穩定回 "invalid JSON input"。
 //   改為不傳字型編譯，渲染為 SVG 後注入 font-family 覆寫，交由 librsvg(sharp) 以系統「Microsoft JhengHei」實際描繪。
 //   D2 v0.7 內建 CJK 全形寬度量測，box 寬即使長中文亦不溢出（已實測）。
-import { D2 } from '@terrastruct/d2'
-import sharp from 'sharp'
+// @terrastruct/d2 與 sharp 為本產線專屬重依賴, 於函式內動態載入(延遲載入):
+//   模組層載入會令「僅用其他產線」的使用者也付出載入成本, 且 d2 上游缺陷會連帶影響其他產線
 import { colorOf, isGroupCls } from '../common/palette.mjs'
 
 // ── 字型注入 ────────────────────────────────────────────────────────────────
@@ -68,27 +68,27 @@ function styLines(cls, isGroup) {
 
 // ── 取節點在 D2 中的完整路徑(用於邊的 from/to 引用) ────────────────────────
 // D2 巢狀容器中子節點須以 "父.子" 表示；遞迴向上追溯直到頂層。
-function qualifiedId(nodeId, parentMap) {
+function qualifiedId(nodeId, parentMap, qid) {
     const parts = []
     let cur = nodeId
     while (cur) {
         parts.unshift(cur)
         cur = parentMap[cur]
     }
-    return parts.join('.')
+    return parts.map(qid).join('.')
 }
 
 // ── 遞迴產生 D2 區塊：容器（群組）巢狀展開 ────────────────────────────────────
 // childrenMap: parentId → [node, ...]
 // parentMap: nodeId → parentId | undefined
-function renderNode(nd, childrenMap, parentMap, dataDir, indent) {
+function renderNode(nd, childrenMap, parentMap, dataDir, indent, qid) {
     const pad = ' '.repeat(indent)
     const isGroup = isGroupCls(nd.cls)
     const lines = []
 
     if (isGroup) {
         // 群組容器：開 block，在內部設 direction + style，再遞迴展開子節點
-        lines.push(`${pad}${nd.id}: "${esc(nd.label)}" {`)
+        lines.push(`${pad}${qid(nd.id)}: "${esc(nd.label)}" {`)
         // 若群組本身有子節點，為其設定方向（延用圖的頂層方向）
         const kids = childrenMap[nd.id] || []
         if (kids.length > 0) {
@@ -98,12 +98,12 @@ function renderNode(nd, childrenMap, parentMap, dataDir, indent) {
             lines.push(`${pad}${sl}`)
         }
         for (const kid of kids) {
-            lines.push(renderNode(kid, childrenMap, parentMap, dataDir, indent + 2))
+            lines.push(renderNode(kid, childrenMap, parentMap, dataDir, indent + 2, qid))
         }
         lines.push(`${pad}}`)
     } else {
         // 一般節點（含 diamond）
-        lines.push(`${pad}${nd.id}: "${esc(nd.label)}" {`)
+        lines.push(`${pad}${qid(nd.id)}: "${esc(nd.label)}" {`)
         for (const sl of styLines(nd.cls, false)) {
             lines.push(`${pad}${sl}`)
         }
@@ -116,6 +116,20 @@ function renderNode(nd, childrenMap, parentMap, dataDir, indent) {
 // ── translate：標準數據 → D2 DSL 字串 ─────────────────────────────────────────
 // 邊一律在頂層宣告，跨群組時用完整路徑（parent.child）讓 D2 正確解析。
 function translate(data) {
+    // D2 保留字(top/left/right/bottom/style/label/shape/near/width/height 等)不可作識別子 → 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
+    }
+
     // 建立 parentMap（nodeId → parentId） 與 childrenMap（parentId → [node]）
     const parentMap = {}
     const childrenMap = {}
@@ -137,13 +151,13 @@ function translate(data) {
 
     // 頂層節點（含群組容器）
     for (const nd of topNodes) {
-        blocks.push(renderNode(nd, childrenMap, parentMap, data.dir, 0))
+        blocks.push(renderNode(nd, childrenMap, parentMap, data.dir, 0, qid))
     }
 
     // 邊：全部在頂層，跨層路徑用 qualifiedId 展開
     for (const ed of data.edges) {
-        const src = qualifiedId(ed.from, parentMap)
-        const dst = qualifiedId(ed.to, parentMap)
+        const src = qualifiedId(ed.from, parentMap, qid)
+        const dst = qualifiedId(ed.to, parentMap, qid)
         let s = `${src} -> ${dst}`
         if (ed.label) s += `: "${esc(ed.label)}"`
         if (ed.kind === 'dashed') s += ` { style.stroke-dash: 4 }`
@@ -157,11 +171,12 @@ function translate(data) {
 // pad=40 與 themeID=0 為通用常數，對所有 9 張圖一致；無逐圖數值。
 const baseOpt = { layout: 'dagre', pad: 40, themeID: 0 }
 
-// ── 單張渲染：正規化繪圖數據 → PNG Buffer ─────────────────────────────────────
+// ── 單張渲染核心：正規化繪圖數據 → 後處理完成之 SVG 字串 ──────────────────────
 // data 結構同 FIGURES[n].data（{ dir, nodes, edges }），caller 須先做 label 衍生。
 // D2 建構時即起常駐 worker 且無公開關閉 API（worker 為 node worker_threads 實例），
 // 若掛在模組層, 光 import 本檔就會令 caller 程序無法自然結束；故逐次建立並於 finally terminate。
-export async function genPng(data, opt = {}) {
+async function d2Svg(data) {
+    const { D2 } = await import('@terrastruct/d2')
     const d2inst = new D2()
     try {
         const d2src = translate(data)
@@ -169,14 +184,26 @@ export async function genPng(data, opt = {}) {
         let svg = await d2inst.render(res.diagram, res.renderOptions)
         svg = injectEdgeLabelHalo(svg)
         svg = injectFont(svg)
-        // density 通用公式：依 SVG viewBox 寬推算，讓輸出寬約落在 1600–2200px
-        const m = svg.match(/viewBox="0 0 (\d+(?:\.\d+)?) (\d+(?:\.\d+)?)"/)
-        const w = m ? parseFloat(m[1]) : 1000
-        const density = 96 * Math.min(2.4, Math.max(1.4, 1700 / w))
-        return await sharp(Buffer.from(svg), { density }).png().toBuffer()
+        return svg
     }
     finally {
         await d2inst.ready.catch(() => {})
         if (d2inst.worker && d2inst.worker.terminate) await d2inst.worker.terminate()
     }
 }
+
+// ── 單張渲染 → PNG Buffer ────────────────────────────────────────────────────
+export async function genPng(data, opt = {}) {
+    const { default: sharp } = await import('sharp')
+    const svg = await d2Svg(data)
+    // density 通用公式：依 SVG viewBox 寬推算，讓輸出寬約落在 1600–2200px
+    const m = svg.match(/viewBox="0 0 (\d+(?:\.\d+)?) (\d+(?:\.\d+)?)"/)
+    const w = m ? parseFloat(m[1]) : 1000
+    const density = 96 * Math.min(2.4, Math.max(1.4, 1700 / w))
+    return await sharp(Buffer.from(svg), { density }).png().toBuffer()
+}
+
+// ── 單張渲染 → SVG 字串（D2 引擎原生輸出 + 光暈/字型後處理） ───────────────────
+export async function genSvg(data, opt = {}) {
+    return await d2Svg(data)
+}

package/src/p6/README.md

@@ -6,7 +6,7 @@
 - **渲染方式**：以 `chromium.launch()` 開啟無頭瀏覽器，`page.setContent(html)` 載入內嵌 G6 頁面，於頁面內呼叫 `window.renderFig()`，以 `G6.Graph` + `layout: { type:'antv-dagre' }` 完成排版與渲染。
 - **截圖／輸出**：呼叫 `graph.toDataURL({ mode:'overall' })` 取得整圖 DataURL（非 viewport 截圖），透過 `window.snap()` 取回後在 Node 端解 base64，組成 `Buffer` 回傳（不寫檔）。
 - **解析度**：`browser.newPage({ deviceScaleFactor: 2 })`，輸出為 2× 實體像素解析度的 PNG。
-- **介面**：`genPng(data, opt)` 為單張渲染函式，由 `src/WFlowchart.mjs` 統一調用；`data` 為正規化繪圖數據 `{ dir, nodes, edges }`（caller 已完成 label 衍生）。每次呼叫皆逐次 `chromium.launch()`，並在 `finally` 呼叫 `browser.close()`，不跨圖共用頁面。
+- **介面**：`genPng(data, opt)` 為單張渲染函式，由 `src/WFlowchart.mjs` 統一調用；`data` 為正規化繪圖數據 `{ dir, nodes, edges }`（caller 已完成 label 衍生）。每次呼叫皆逐次 `chromium.launch()`，並在 `finally` 呼叫 `browser.close()`，不跨圖共用頁面；同結構之 `genSvg(data, opt)` 換用 `@antv/g-lite` + `@antv/g-svg` 之官方 renderer API 以 SVG renderer 重繪（序列化前將相機 transform 歸零），與 `genPng` 共用同一套 `translate`/排版/樣式邏輯，經忠實度驗證。
 
 ## 產製原理(資料驅動)
 

package/src/p6/gen.mjs

@@ -16,6 +16,10 @@ import { pkgScript } from '../common/pkg.mjs'
 
 // G6 v5 由本機 node_modules 內聯注入(取代 CDN, 斷網環境可用)
 const G6_JS = pkgScript('@antv/g6/dist/g6.min.js')
+// genSvg 專用:@antv/g-svg renderer(取代預設 canvas renderer, 產出 SVG DOM)。
+//   依賴 @antv/g-lite UMD(暴露全域 window.G)須先於 g-svg UMD 載入(g-svg UMD 讀取既有 window.G 掛載 window.G.SVG)。
+const G_LITE_JS = pkgScript('@antv/g-lite/dist/index.umd.min.js')
+const G_SVG_JS = pkgScript('@antv/g-svg/dist/index.umd.min.js')
 
 // ===== 通用排版常數(全圖共用, 無逐圖客製) =====
 const CANVAS = 2200          // 大畫布:給足夠空間, 配合 autoFit:'view' 自動縮放, 不逐圖設 w/h
@@ -52,15 +56,22 @@ function translate(data) {
     const nodes = []
     const combos = []
     // G6 v5 不接受以 combo id 當邊端點; 建「容器 → 代表葉節點」對照, 將指向容器的邊改接其代表成員。
-    //   通用化舊版「層級邊改走成員節點(fe1→if1)」的手法:取各容器第一個直屬葉節點為代表, 不逐圖寫死成員 id。
+    //   通用化舊版「層級邊改走成員節點(fe1→if1)」的手法:取容器內數據序第一個「可達」葉節點為代表;
+    //   容器內可能只有子容器(深巢狀), 故須遞迴下鑽, 不能只看直屬成員。
     const comboIds = new Set(data.nodes.filter(nd => isGroupCls(nd.cls)).map(nd => nd.id))
-    const kpRepByCombo = {}
+    const childrenOf = {}
     for (const nd of data.nodes) {
-        if (nd.group && comboIds.has(nd.group) && !isGroupCls(nd.cls) && !(nd.group in kpRepByCombo)) {
-            kpRepByCombo[nd.group] = nd.id
+        if (nd.group) (childrenOf[nd.group] = childrenOf[nd.group] || []).push(nd)
+    }
+    const firstLeaf = (cid) => {
+        for (const ch of (childrenOf[cid] || [])) {
+            if (!isGroupCls(ch.cls)) return ch.id
+            const r = firstLeaf(ch.id)
+            if (r) return r
         }
+        return null
     }
-    const resolveEnd = (id) => (comboIds.has(id) && kpRepByCombo[id]) ? kpRepByCombo[id] : id
+    const resolveEnd = (id) => (comboIds.has(id) && firstLeaf(id)) || id
     for (const nd of data.nodes) {
         const c = colorOf(nd.cls)
         if (isGroupCls(nd.cls)) {
@@ -184,3 +195,95 @@ export async function genPng(data, opt = {}) {
         await browser.close()
     }
 }
+
+// ===== genSvg 專用渲染外殼 =====
+//   與 genPng 完全獨立之頁面/renderer 流程(genPng 之 html/renderFig/snap 不受影響、行為不變)。
+//   換用 @antv/g-svg renderer(取代預設 canvas renderer)產出 SVG DOM, 其餘 translate/layout/樣式邏輯
+//   (dagre 排版、緊湊間距、z-order、字型)與 genPng 完全共用, 故版面結構/顏色/文字與 PNG 版一致。
+const htmlSvg = `<!doctype html><html lang="zh-Hant"><head><meta charset="utf-8">
+<script>${G_LITE_JS}</script>
+<script>${G_SVG_JS}</script>
+<script>${G6_JS}</script>
+</head><body style="margin:0;background:#fff">
+<div id="g6" style="background:#fff"></div>
+<script>
+window.renderFigSvg = async function(g, rankdir, nodesep, ranksep, canvas, font, comboZ, edgeZ){
+  try {
+    const el = document.getElementById('g6')
+    el.style.width = canvas + 'px'; el.style.height = canvas + 'px'
+    if (window.__graph) { try { window.__graph.destroy() } catch(e){} }
+    const graph = new G6.Graph({
+      container: el, width: canvas, height: canvas, autoFit:'view',
+      renderer: () => new window.G.SVG.Renderer(),
+      data: { nodes: g.nodes, edges: g.edges, combos: g.combos },
+      layout: { type:'antv-dagre', rankdir: rankdir, nodesep: nodesep, ranksep: ranksep, sortByCombo: (g.combos && g.combos.length>0) },
+      combo: { type:'rect', style:{ zIndex: comboZ, padding:[30,18,18,18], labelPlacement:'top', labelFontFamily: font } },
+      edge: { type:'polyline', style:{ zIndex: edgeZ, lineWidth:2.2, endArrow:true, labelFontFamily: font } },
+      node: { style:{ labelFontFamily: font } },
+    })
+    window.__graph = graph
+    await graph.render()
+    await new Promise(r=>setTimeout(r,300))
+    return { ok:true }
+  } catch(e){ return { ok:false, err:String(e&&(e.stack||e.message)||e).slice(0,400) } }
+}
+// 取 main layer 之 SVG DOM(SVG renderer 下唯一承載節點/邊/combo 之 layer, background/label/transient 三層無內容),
+// 以 canvas.getBounds() 對齊 toDataURL({mode:'overall'}) 之緊裁切邊界改寫 viewBox/width/height, 補白底矩形。
+window.snapSvg = async function(){
+  try {
+    await new Promise(r=>setTimeout(r,200))
+    const canvas = window.__graph.getCanvas()
+    const bounds = canvas.getBounds()
+    const minX = bounds.min[0], minY = bounds.min[1]
+    const w = bounds.max[0] - minX, h = bounds.max[1] - minY
+    const mainEl = canvas.getLayer('main').getContextService().getDomElement()
+    const svg = mainEl.cloneNode(true)
+    // canvas.getBounds() 回傳世界座標(排版原始座標, 未經 camera 縮放平移); 但複製之 DOM 內容掛在
+    // #g-svg-camera 群組下, 帶有互動視圖之 camera transform(autoFit:'view' 縮放平移)。
+    // 兩者座標系不同, 混用會裁切錯位, 故先歸零 camera transform, 使內容回到與 bounds 相同之世界座標。
+    const cameraEl = svg.querySelector('#g-svg-camera')
+    if (cameraEl) cameraEl.removeAttribute('transform')
+    svg.setAttribute('xmlns', 'http://www.w3.org/2000/svg')
+    svg.setAttribute('viewBox', minX + ' ' + minY + ' ' + w + ' ' + h)
+    svg.setAttribute('width', String(Math.ceil(w)))
+    svg.setAttribute('height', String(Math.ceil(h)))
+    svg.removeAttribute('tabindex')
+    svg.style.background = ''
+    svg.style.pointerEvents = ''
+    svg.style.gridArea = ''
+    svg.style.outline = ''
+    const bgRect = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+    bgRect.setAttribute('x', String(minX)); bgRect.setAttribute('y', String(minY))
+    bgRect.setAttribute('width', String(w)); bgRect.setAttribute('height', String(h))
+    bgRect.setAttribute('fill', '#fff')
+    svg.insertBefore(bgRect, svg.firstChild)
+    const out = svg.outerHTML.replace(/&nbsp;/g, '&#160;')
+    return { ok:true, svg: out }
+  } catch(e){ return { ok:false, err:String(e&&(e.stack||e.message)||e).slice(0,400) } }
+}
+window.__readySvg=true
+</script></body></html>`
+
+// 單張渲染:同 genPng 之輸入(單份正規化繪圖數據), 回傳 SVG 字串(緊裁切範圍對齊 genPng 之 toDataURL overall)。
+//   獨立頁面/renderer 流程(見上), genPng 之 canvas 渲染行為不受影響。
+export async function genSvg(data, opt = {}) {
+    const browser = await chromium.launch()
+    try {
+        const page = await browser.newPage()
+        const errs = []
+        page.on('pageerror', e => errs.push(e.message))
+        page.on('console', m => { if (m.type() === 'error') errs.push('c:' + m.text()) })
+        await page.setContent(htmlSvg, { waitUntil: 'load' })
+        await page.waitForFunction(() => window.__readySvg, { timeout: 60000 }).catch(() => {})
+        await page.evaluate(() => document.fonts && document.fonts.ready)
+        const g = translate(data)
+        const r = await page.evaluate(([gg, rd, ns, rs, cv, ft, cz, ez]) => window.renderFigSvg(gg, rd, ns, rs, cv, ft, cz, ez),
+            [g, data.dir, NODESEP, RANKSEP, CANVAS, FONT, COMBO_Z, EDGE_Z])
+        if (!r.ok) throw new Error('renderFigSvg failed :: ' + String(r.err).split('\n')[0])
+        const res = await page.evaluate(() => window.snapSvg())
+        if (!res.ok) throw new Error('snapSvg failed :: ' + res.err)
+        return res.svg
+    } finally {
+        await browser.close()
+    }
+}

package/src/p7/README.md

@@ -7,7 +7,7 @@
 - **渲染方式**：排版完成後以 `P.fitToContent({ padding: 28, allowNewOrigin: 'any', useModelGeometry: true })` 讓 JointJS Paper 自適應內容邊界，截圖目標為 `#paper svg`（`page.$('#paper svg').screenshot()`），直接輸出 PNG。
 - **解析度**：`browser.newPage({ deviceScaleFactor: 2 })` 以 2 倍像素密度開頁，截出的 PNG 實際像素為邏輯尺寸的兩倍，保有高清品質。
 - **字型**：頁內使用 `Microsoft JhengHei`（微軟正黑體）作為主字型，canvas 量測與 JointJS 渲染均使用同一 `FONT` 字串，確保量測結果與渲染結果一致。
-- **調用方式**：本模組僅匯出 `genPng(data, opt) → Promise<Buffer>`，輸入為正規化繪圖數據 `{ dir, nodes, edges }`，回傳 PNG 之 Node Buffer；由 `src/WFlowchart.mjs` 統一匯入並依 `p7` 鍵值調用，本身不寫檔、不涉及批次流程。
+- **調用方式**：本模組匯出 `genPng(data, opt) → Promise<Buffer>` 與 `genSvg(data, opt) → Promise<string>`，輸入皆為正規化繪圖數據 `{ dir, nodes, edges }`；`genPng` 回傳 PNG 之 Node Buffer，`genSvg` 取 `#paper svg` 之 DOM 序列化結果並修正為 standalone SVG（補 `xmlns`、`width`/`height` 由 `100%` 改為 `fitToContent` 後之實際像素值、移除依賴容器定位之 `position:absolute;inset:0`）；由 `src/WFlowchart.mjs` 統一匯入並依 `p7` 鍵值調用，本身不寫檔、不涉及批次流程。
 
 ## 產製原理（資料驅動）
 

package/src/p7/gen.mjs

@@ -360,9 +360,9 @@ window.renderFig = renderFig
 window.__ready = true
 </script></body></html>`
 
-// genPng(data, opt) — 單張渲染:輸入正規化繪圖數據({dir,nodes,edges}, caller 已先做 label 衍生),
-//   重用上方 translate/HTML/渲染管線, 回傳 PNG 之 Node Buffer(caller 自行決定寫檔或其他用途)。
-export async function genPng(data, opt = {}) {
+// 渲染單張至就緒頁面(#paper svg 已完成排版渲染), 回傳 {browser,page,res}(res 含 fitToContent 後之 w/h);
+//   caller 負責 close browser。渲染失敗(res.ok=false)或例外時, 先 close browser 再 rethrow。
+async function renderFigPage(data) {
     const browser = await chromium.launch()
     try {
         const page = await browser.newPage({ deviceScaleFactor: 2 })
@@ -378,9 +378,48 @@ export async function genPng(data, opt = {}) {
         const { els, rankDir } = translate(data)
         const res = await page.evaluate(([e, rd, s]) => window.renderFig(e, rd, s), [els, rankDir, SEP])
         if (!res.ok) throw new Error(res.err + (res.stack ? '\n' + res.stack : ''))
+        return { browser, page, res }
+    }
+    catch (err) {
+        await browser.close()
+        throw err
+    }
+}
+
+// genPng(data, opt) — 單張渲染:輸入正規化繪圖數據({dir,nodes,edges}, caller 已先做 label 衍生),
+//   重用上方 translate/HTML/渲染管線, 回傳 PNG 之 Node Buffer(caller 自行決定寫檔或其他用途)。
+export async function genPng(data, opt = {}) {
+    const { browser, page } = await renderFigPage(data)
+    try {
         const el = await page.$('#paper svg')
         return await el.screenshot()
     } finally {
         await browser.close()
     }
 }
+
+// genSvg(data, opt) — 單張渲染 → standalone SVG 字串:
+//   取 #paper svg 之 outerHTML, 修正使其脫離 #paper 容器後仍忠實:
+//     1. 補 xmlns(JointJS 只寫 xmlns:xlink, 缺 xmlns 非合法 standalone SVG)
+//     2. width/height 由 JointJS 寫死的 "100%" 改為 fitToContent 後之實際像素值(res.w/res.h)
+//        (100% 依賴 #paper 容器之 inline width/height, 脫離容器後無父層可依附)
+//     3. 移除 position:absolute;inset:0(同上, 依賴容器定位, standalone 時會撐滿最近定位祖先/viewport)
+//   svg 內已含 JointJS 自身注入之 <style>(non-scaling-stroke), outerHTML 序列化時隨之保留, 無需另行處理。
+//   &nbsp; 正規化為 &#160; 使其為合法 XML。
+export async function genSvg(data, opt = {}) {
+    const { browser, page, res } = await renderFigPage(data)
+    try {
+        let outer = await page.$eval('#paper svg', el => el.outerHTML)
+        outer = outer.replace(/^<svg([^>]*)>/, (m0, attrs) => {
+            let a = attrs
+            if (!/\bxmlns=/.test(a)) a = ' xmlns="http://www.w3.org/2000/svg"' + a
+            a = a.replace(/\swidth="100%"/, ` width="${res.w}"`)
+            a = a.replace(/\sheight="100%"/, ` height="${res.h}"`)
+            a = a.replace(/position:\s*absolute;\s*inset:\s*[^;]*;\s*/, '')
+            return `<svg${a}>`
+        })
+        return outer.replace(/&nbsp;/g, '&#160;').trim()
+    } finally {
+        await browser.close()
+    }
+}

package/src/p8/README.md

@@ -6,7 +6,7 @@
 - **載入方式**：Node 端以 Playwright 建立 Chromium 頁面，將完整 HTML 字串（含內聯 CSS 與兩段內聯 `<script>`）透過 `page.setContent()` 注入；繪圖邏輯全部在頁內 `<script>` 執行，Node 端僅負責驅動與截圖。
 - **渲染與截圖**：頁內 `window.renderFig(fig)` 依序計算尺寸 → dagre 排版 → `lf.render()` 渲染完後以 `setTimeout(..., 200)` 等待 DOM 穩定，回傳 Promise；Node 端再呼叫 `page.evaluate(() => document.fonts.ready)` 確保字型載入完畢，最後以 `page.locator('#app').screenshot()` 截取 `#app` 元素為 PNG Buffer 回傳（不寫檔）。
 - **解析度**：`browser.newPage({ deviceScaleFactor: 2 })`，輸出為 2× 實體像素密度（HiDPI），寬高由計算所得邏輯像素乘以 2 輸出。
-- **調用方式**：本模組僅匯出 `genPng(data, opt) → Promise<Buffer>`，輸入為正規化繪圖數據 `{ dir, nodes, edges }`，回傳 PNG 之 Node Buffer；由 `src/WFlowchart.mjs` 統一匯入並依 `p8` 鍵值調用，本身不寫檔、不涉及批次流程。
+- **調用方式**：本模組匯出 `genPng(data, opt) → Promise<Buffer>` 與 `genSvg(data, opt) → Promise<string>`，輸入皆為正規化繪圖數據 `{ dir, nodes, edges }`；`genSvg` 序列化圖面 svg（`lf-canvas-overlay`），並將 LogicFlow CSS 內嵌進 SVG（文字自動換行之 `foreignObject` 標籤樣式依賴此 CSS）；由 `src/WFlowchart.mjs` 統一匯入並依 `p8` 鍵值調用，本身不寫檔、不涉及批次流程。
 
 ## 產製原理（資料驅動）
 

package/src/p8/gen.mjs

@@ -394,8 +394,9 @@ window.renderFig = function(fig){ return new Promise(function(resolve){
 window.__ready = true
 </script></body></html>`
 
-// 對外: 單張正規化數據(同 FIGURES[n].data 結構) → PNG Buffer。重用上方 translate/HTML/渲染管線, 自行開關 browser, 不寫檔。
-export async function genPng(data, opt = {}) {
+// 內部 helper: 開 browser → 灌入 html → 等待 LF 就緒 → renderFig(data) 畫出圖面, 回傳 { browser, page }(呼叫端負責 close)。
+//   失敗時(含 renderFig 回報 !ok)於此處關閉 browser 後 rethrow, 呼叫端不需重複收拾。
+async function renderToReadyPage(data) {
     const browser = await chromium.launch()
     try {
         const page = await browser.newPage({ deviceScaleFactor: 2 })
@@ -409,8 +410,46 @@ export async function genPng(data, opt = {}) {
         const res = await page.evaluate((fig) => window.renderFig(fig), fig)
         if (!res.ok) throw new Error(res.err || 'renderFig failed')
         await page.evaluate(() => document.fonts && document.fonts.ready)
+        return { browser, page, res }
+    } catch (e) {
+        await browser.close()
+        throw e
+    }
+}
+
+// 對外: 單張正規化數據(同 FIGURES[n].data 結構) → PNG Buffer。重用上方 translate/HTML/渲染管線, 自行開關 browser, 不寫檔。
+export async function genPng(data, opt = {}) {
+    const { browser, page } = await renderToReadyPage(data)
+    try {
         return await page.locator('#app').screenshot()
     } finally {
         await browser.close()
     }
 }
+
+// 對外: 單張正規化數據 → 忠實且 standalone 的 SVG 字串。
+//   #app 內實際有 3 個 svg(canvas-overlay 圖面本體 / modification-overlay 選取輔助層(無內容)/ lf-grid 背景格線(display:none)),
+//   真正含 .lf-node/.lf-edge 圖元的是 svg.lf-canvas-overlay, 序列化取此元素即可(transform 為單位矩陣, 座標已是絕對像素)。
+//   節點/邊樣式多為行內屬性(fill/stroke/font-family...皆已內聯), 但文字自動換行採 foreignObject 內嵌 HTML div,
+//   其置中(flex)/字重/寬度等版面由 LOGICFLOW_CSS 之 .lf-node-text-auto-wrap(-content) class 決定, 故仍需嵌入該 CSS 才能忠實呈現。
+export async function genSvg(data, opt = {}) {
+    const { browser, page, res } = await renderToReadyPage(data)
+    try {
+        let svg = await page.evaluate(() => document.querySelector('svg.lf-canvas-overlay').outerHTML)
+        const openTagMatch = svg.match(/^<svg[^>]*>/)
+        if (!openTagMatch) throw new Error('genSvg: 找不到圖面 svg 根元素')
+        let openTag = openTagMatch[0]
+            .replace('width="100%"', `width="${res.w}"`)
+            .replace('height="100%"', `height="${res.h}"`)
+        openTag = openTag.replace(/>$/, ` viewBox="0 0 ${res.w} ${res.h}">`)
+        svg = openTag + svg.slice(openTagMatch[0].length)
+        // 嵌入 CSS(LOGICFLOW_CSS + 頁內字型規則) + 白底(比照 #app 背景), 使脫離頁面仍忠實呈現
+        const inject = `<style>${LOGICFLOW_CSS}\n* { font-family: ${FONT}; }</style>`
+            + `<rect x="0" y="0" width="${res.w}" height="${res.h}" fill="#fff"></rect>`
+        svg = svg.replace('<g transform', inject + '<g transform')
+        svg = svg.replace(/&nbsp;/g, '&#160;')
+        return svg
+    } finally {
+        await browser.close()
+    }
+}

package/src/p9/README.md

@@ -8,7 +8,7 @@
 - **截圖目標**：對 `#shot` 元素截圖（`page.locator('#shot').screenshot()`）；`#shot` 為 `display:inline-block` 的 div，內含 `#stage`（React Flow 掛載點），外加 `padding:24px` 白邊，截出的 PNG 即為完整含留白之圖片。
 - **解析度**：`browser.newPage({ deviceScaleFactor: 2 })` 開啟 2x 縮放，所有量測與佈局座標仍以 CSS px 計算，截出的 PNG 實際像素為畫布尺寸之 2 倍，確保中文字型清晰。
 - **字型**：`Microsoft JhengHei, sans-serif`，中文主字型一致貫穿節點、標籤、邊標籤。
-- **呼叫入口**：`export async function genPng(data, opt = {})` 為唯一對外介面，回傳 `Promise<Buffer>`（PNG）；由 `src/WFlowchart.mjs` 之 `GENS.p9` 統一調用（`mode: 'p9'`）。`data` 為正規化繪圖數據 `{ dir, nodes, edges }`；`opt` 保留擴充，目前原樣接收但未使用。
+- **呼叫入口**：`export async function genPng(data, opt = {})` 為唯一對外介面，回傳 `Promise<Buffer>`（PNG）；由 `src/WFlowchart.mjs` 之 `GENS.p9` 統一調用（`mode: 'p9'`）。`data` 為正規化繪圖數據 `{ dir, nodes, edges }`；`opt` 保留擴充，目前原樣接收但未使用。**不支援 SVG 輸出**（本產線節點為 React Flow 之 HTML div，非純 SVG，無法序列化為 standalone SVG）。
 
 ## 產製原理（資料驅動）
 

package/src/p9/gen.mjs

@@ -13,12 +13,19 @@ import { pkgScript, pkgText } from '../common/pkg.mjs'
 const __dir = dirname(fileURLToPath(import.meta.url))
 // React / ReactDOM / @xyflow/react(UMD)/ @dagrejs/dagre 由本機 node_modules 內聯注入(取代 esm.sh, 斷網環境可用)
 //   replace 用函式形式回傳, 避免庫碼內 $ 序列被當作替換樣板
-const html = fs.readFileSync(`${__dir}/page9.html`, 'utf8')
-    .replace('/*__XYFLOW_CSS__*/', () => pkgText('@xyflow/react/dist/style.css'))
-    .replace('/*__REACT_JS__*/', () => pkgScript('react/umd/react.production.min.js'))
-    .replace('/*__REACT_DOM_JS__*/', () => pkgScript('react-dom/umd/react-dom.production.min.js'))
-    .replace('/*__XYFLOW_JS__*/', () => pkgScript('@xyflow/react/dist/umd/index.js'))
-    .replace('/*__DAGRE_JS__*/', () => pkgScript('@dagrejs/dagre/dist/dagre.min.js'))
+//   首次呼叫才讀檔組頁(延遲載入): 模組層即讀會令「僅用其他產線」的載入方也付出讀檔成本
+let _html = null
+function getHtml() {
+    if (_html === null) {
+        _html = fs.readFileSync(`${__dir}/page9.html`, 'utf8')
+            .replace('/*__XYFLOW_CSS__*/', () => pkgText('@xyflow/react/dist/style.css'))
+            .replace('/*__REACT_JS__*/', () => pkgScript('react/umd/react.production.min.js'))
+            .replace('/*__REACT_DOM_JS__*/', () => pkgScript('react-dom/umd/react-dom.production.min.js'))
+            .replace('/*__XYFLOW_JS__*/', () => pkgScript('@xyflow/react/dist/umd/index.js'))
+            .replace('/*__DAGRE_JS__*/', () => pkgScript('@dagrejs/dagre/dist/dagre.min.js'))
+    }
+    return _html
+}
 
 // 正規化數據 → page9.html renderFig spec
 //   標籤「不預折」, 原樣傳入, 由 page9.html 量測 div(max-width + overflow-wrap)自然折行:
@@ -47,7 +54,7 @@ export async function genPng(data, opt = {}) {
         const errs = []
         page.on('pageerror', e => errs.push(e.message))
         page.on('console', m => { if (m.type() === 'error') errs.push('c:' + m.text().slice(0, 200)) })
-        await page.setContent(html, { waitUntil: 'load' })
+        await page.setContent(getHtml(), { waitUntil: 'load' })
         await page.waitForFunction(() => document.title === 'READY' || document.title === 'FAIL', { timeout: 60000 }).catch(() => {})
         const boot = await page.evaluate(() => ({ t: document.title, err: window.__err }))
         if (boot.t !== 'READY') throw new Error('BOOT FAIL :: ' + boot.err + ' | ' + errs.slice(0, 6).join(' | '))

package/src/p9/page9.html

@@ -208,13 +208,21 @@ try {
       if (n.parent && grpIds.has(n.parent)) g.setParent(n.id, n.parent)
     }
     // dagre compound 不能對「容器節點」直接連邊(ranking 階段會崩),
-    //   故 ranking 用「代表葉節點」替代容器端點(取該容器第一個葉子後代);
-    //   實際繪線仍用容器框(後段 pickHandles 以絕對 box 計算)。此為通用處理, 非逐圖。
-    const repLeaf = {}
+    //   故 ranking 用「代表葉節點」替代容器端點(取該容器數據序第一個可達葉子後代);
+    //   容器內可能只有子容器(深巢狀), 故須遞迴下鑽。實際繪線仍用容器框(後段 pickHandles 以絕對 box 計算)。此為通用處理, 非逐圖。
+    const childByParent = {}
     for (const n of rawNodes) {
-      if (n.parent && grpIds.has(n.parent) && !grpIds.has(n.id) && repLeaf[n.parent] === undefined) repLeaf[n.parent] = n.id
+      if (n.parent) (childByParent[n.parent] = childByParent[n.parent] || []).push(n)
     }
-    const rankId = id => grpIds.has(id) ? (repLeaf[id] || id) : id
+    const firstLeaf = (gid) => {
+      for (const ch of (childByParent[gid] || [])) {
+        if (!grpIds.has(ch.id)) return ch.id
+        const r = firstLeaf(ch.id)
+        if (r) return r
+      }
+      return null
+    }
+    const rankId = id => grpIds.has(id) ? (firstLeaf(id) || id) : id
     const seenRank = new Set()
     for (const e of rawEdges) {
       const s = rankId(e.s), t = rankId(e.t)