@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/localized/zh-CN/skills/cc-technical-diagrams/assets/quality-examples/README.md

@@ -0,0 +1,14 @@
+# 技术图质量样例
+
+JSON 样例覆盖时序自调用、流程决策回环、架构分组和双向连接。Mermaid 源用于标准时序与流程图；修改布局时保留全部文字和连接关系。
+
+```sh
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input workflow.html --format png --output workflow.png --theme light --scale 2 --manifest workflow.layout.json --output-manifest workflow.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
+node skills/cc-technical-diagrams/scripts/mermaid-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/sequence.mmd --output sequence.svg --report sequence.render.json
+```
+
+PNG 需要本地 Chromium，可用 FEC_BROWSER_PATH 指定路径。Mermaid 需要已安装的 mmdc，不自动安装或使用 CDN；缺失时明确记录并使用 JSON/HTML。需要手工编辑的架构图复用 cc-drawio-studio，大型拓扑可选 Graphviz。
+
+按交付阅读尺寸检查 1x 和 2x 图片，检查形状内部文字、标签和箭头、分支返回、回环、分组及明暗主题对比。几何 QA 不能替代看图。显式尺寸不足或 waypoints 受阻时报告问题，在源级修复且保留意图。默认最多修复两轮，用户要求时最多五轮，未解决则报告部分验收。

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/assets/quality-examples/sequence.mmd

@@ -1,21 +1,21 @@
-sequenceDiagram
- participant Web as 用户浏览器客户端
- participant API as 订单服务接口
- participant DB as 持久化数据库
- Web->>API: 查询订单详细信息与当前支付状态
- API->>API: 验证身份与订单访问权限
- API->>DB: 缓存未命中，读取订单记录
- DB-->>API: 返回订单记录与支付状态
- API-->>Web: 返回查询结果并更新页面
-
- activate API
- alt 缓存命中
- API-->>Web: 返回缓存结果
- else 缓存未命中
- loop 重试失败查询
- API->>DB: 读取记录
- DB-->>API: 返回结果
- end
- end
- API-)Web: 异步更新通知
- deactivate API
+sequenceDiagram
+ participant Web as 用户浏览器客户端
+ participant API as 订单服务接口
+ participant DB as 持久化数据库
+ Web->>API: 查询订单详细信息与当前支付状态
+ API->>API: 验证身份与订单访问权限
+ API->>DB: 缓存未命中，读取订单记录
+ DB-->>API: 返回订单记录与支付状态
+ API-->>Web: 返回查询结果并更新页面
+
+ activate API
+ alt 缓存命中
+ API-->>Web: 返回缓存结果
+ else 缓存未命中
+ loop 重试失败查询
+ API->>DB: 读取记录
+ DB-->>API: 返回结果
+ end
+ end
+ API-)Web: 异步更新通知
+ deactivate API

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/assets/quality-examples/workflow.mmd

@@ -1,7 +1,7 @@
-flowchart TD
- A([提交订单申请]) --> B{检查订单信息是否完整且符合审核条件}
- B -->|信息完整| C[人工审批并记录处理意见]
- B -->|需要补充| D[补充缺失材料后重新提交]
- D -->|重新审核| B
- C -->|审批通过| E[(保存审批结果并异步通知申请人)]
- E -->|通知成功| F([处理完成])
+flowchart TD
+ A([提交订单申请]) --> B{检查订单信息是否完整且符合审核条件}
+ B -->|信息完整| C[人工审批并记录处理意见]
+ B -->|需要补充| D[补充缺失材料后重新提交]
+ D -->|重新审核| B
+ C -->|审批通过| E[(保存审批结果并异步通知申请人)]
+ E -->|通知成功| F([处理完成])

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/references/diagram-workflows.md

@@ -20,7 +20,7 @@
 启动本地服务：
 
 ```bash
-node skills/fec-image-generation/scripts/interactive-diagram-server.mjs --port 6100
+node skills/cc-technical-diagrams/scripts/interactive-diagram-server.mjs --port 6100
 ```
 
 打开 `http://127.0.0.1:6100/?s=meaningful-session-id`，再向 `/cmd?s=meaningful-session-id` 发送命令。每张图都必须使用唯一 session id。先发送 `init`，再添加节点，最后添加连线；每条命令尽量小，让浏览器能持续增量更新。
@@ -67,7 +67,7 @@ UML 覆盖优先走确定性源：class、ER、state-machine、activity 和 sequ
 
 ## 流程工作流
 
-用户需要浏览器可打开的流程地图、审批流、自动化 runbook、事故流程或循环运营流程，并且需要泳道、步骤编号、参与者、决策、异常路径和摘要卡片时，优先使用 HTML `workflow` IR。流程必须作为 `.drawio` 文件长期维护、需要 diagrams.net 编辑、官方形状库、手工泳道维护或交付后由利益相关方继续修改时，改用 `fec-drawio-studio`。
+用户需要浏览器可打开的流程地图、审批流、自动化 runbook、事故流程或循环运营流程，并且需要泳道、步骤编号、参与者、决策、异常路径和摘要卡片时，优先使用 HTML `workflow` IR。流程必须作为 `.drawio` 文件长期维护、需要 diagrams.net 编辑、官方形状库、手工泳道维护或交付后由利益相关方继续修改时，改用 `cc-drawio-studio`。
 
 ## 导出指引
 
@@ -76,6 +76,6 @@ UML 覆盖优先走确定性源：class、ER、state-machine、activity 和 sequ
 
 ## 质量交付约定
 
-标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 fec-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
 
 扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/localized/zh-CN/skills/{fec-image-generation → cc-technical-diagrams}/references/html-technical-diagrams.md

@@ -7,7 +7,7 @@
 | 需求 | 优先选择 |
 | ---- | -------- |
 | 小型 Markdown 维护图 | Mermaid、Graphviz 或 SVG |
-| 后续人工编辑的图源 | `fec-drawio-studio` 和 `.drawio` |
+| 后续人工编辑的图源 | `cc-drawio-studio` 和 `.drawio` |
 | 浏览器可打开的主题化技术图 | HTML 技术图路线 |
 | 位图优先的视觉概念、海报、产品图或图片编辑 | 图片生成或编辑路线 |
 
@@ -19,7 +19,7 @@
 - `dataflow`：来源、采集、处理、存储、消费者、PII 边界、治理、分析和血缘。
 - `lifecycle`：对象状态、终止状态、重试、等待、取消、超时、部署或订单状态流转。
 
-浏览器可交付的架构总览优先用 `architecture` 模式。需要 `.drawio` 源、官方厂商图标、diagrams.net 手工编辑或复杂自动布局时，改用 `fec-drawio-studio`。
+浏览器可交付的架构总览优先用 `architecture` 模式。需要 `.drawio` 源、官方厂商图标、diagrams.net 手工编辑或复杂自动布局时，改用 `cc-drawio-studio`。
 
 ## 主题化语义图
 
@@ -65,8 +65,8 @@ Agent、memory 和 AI 工作流图优先在 architecture 节点上使用语义 `
 面向 README 或干系人交付时，保留 JSON IR 和 HTML 作为可编辑事实源，再导出 SVG/PNG/JPG 产物：
 
 ```bash
-node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format svg
-node skills/fec-image-generation/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format png --scale 2
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format svg
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input docs/architecture/system-blueprint.html --format png --scale 2
 ```
 
 位图导出会优先使用本机已有的 Chromium 系浏览器。环境无法栅格化 SVG 时，交付生成的 HTML/SVG，并说明 PNG/JPG 导出需要本地浏览器。
@@ -198,7 +198,7 @@ Workflow 连线字段：
 ## 渲染命令
 
 ```bash
-node skills/fec-image-generation/scripts/tech-diagram-render.mjs \
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs \
   --input diagram.json \
   --output diagram.html \
   --type architecture \
@@ -217,7 +217,7 @@ node skills/fec-image-generation/scripts/tech-diagram-render.mjs \
 导出 PNG 后运行：
 
 ```bash
-node skills/fec-image-generation/scripts/png-qa.mjs \
+node skills/cc-technical-diagrams/scripts/png-qa.mjs \
   --png diagram.png \
   --manifest diagram.layout.json \
   --format markdown
@@ -238,6 +238,6 @@ node skills/fec-image-generation/scripts/png-qa.mjs \
 
 ## 质量交付约定
 
-标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 fec-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
 
 扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/localized/zh-CN/skills/cc-technical-diagrams/references/png-qa-autofix.md

@@ -0,0 +1,37 @@
+# PNG 质检与自动修复
+
+## 循环
+
+1. 从可编辑源文件或图像工作流导出 PNG。
+2. 目视检查 PNG。
+3. 有 manifest 时，带 manifest 运行 `png-qa.mjs`。
+4. 将每个问题转化为源文件、提示词或布局变更。
+5. 默认重复 2 轮；用户要求更多修复尝试时最多 5 轮。
+
+## 问题映射
+
+| 问题 | 修复方式 |
+| ----- | ------ |
+| `blank-image` | 检查导出目标、渲染器错误、隐藏图层、透明填充或图像生成失败。 |
+| `edge-clipping` | 增加画布留白、扩大 SVG viewBox、降低主体缩放，或导出更大的画幅。 |
+| `box-overlap` | 增加间距、重排为网格/图层、拆分簇，或对完整标签换行。 |
+| `box-out-of-bounds` | 将节点移入画布，或增大画布尺寸。 |
+| `label-overflow` | 文本换行、加宽框体、保留完整文案，并同时增大字体/容器尺寸。 |
+| `connector-through-label` | 在框体周围添加 waypoints、移动标签，或使用正交布线。 |
+| `connector-stacking` | 偏移平行连接线，或用带标签的分组路径替代重复线条。 |
+| `manifest-canvas-mismatch` | 根据最终导出尺寸重新生成 manifest。 |
+
+## Manifest 质量
+
+只有当 manifest 坐标与导出的 PNG 匹配时，辅助脚本才能判断重叠和连接线问题。若 manifest 过期，先修复 manifest，再重新运行 QA。
+
+## 报告要求
+
+报告 QA 轮数和最终问题列表。若由于源渲染器无法暴露布局坐标而仍有遗留问题，说明哪些检查只能基于图像，哪些需要人工视觉复核。
+
+
+## 质量交付约定
+
+标准序列/流程图优先本地 Mermaid；架构图需要手工编辑时复用 cc-drawio-studio，大型拓扑可选 Graphviz。无本地工具时使用兼容 JSON/HTML，不自动安装或下载。HTML 预览、独立 SVG 和 PNG 使用同源主题样式；导出指定 `--theme light|dark`。PNG 导出等待字体并测量文字，使用 `--manifest source.layout.json --output-manifest image.actual.json` 写出缩放后的像素坐标。QA 必须读取 actual manifest，不能把估算坐标直接用于 2x PNG。
+
+扩展 manifest 保留 canvas/boxes/connectors，增加 coordinateSpace、scale、measurement、groups、labels 与 issues。分组包含节点不算节点重叠。新增 node-text-overflow、label-content-loss、label-out-of-bounds、edge-label-collision、text-overlap 与 degenerate-connector 检查。旧 manifest 保留估算检测。显式尺寸或 waypoints 不满足约束时定位问题，不删字、不改关系、不静默移动。提高导出分辨率不能修复源级溢出。最终 PNG 必须视觉审阅；记录工具可用性、版本、主题、比例、修复轮次和残留问题，未解决时标记部分验收。

package/{skills/fec-image-generation → localized/zh-CN/skills/cc-technical-diagrams}/scripts/diagram-browser.mjs

@@ -22,6 +22,61 @@ export function findBrowser() {
 
 /** @typedef {{evaluate:(expression:string)=>Promise<unknown>,screenshot:(width:number,height:number,scale?:number)=>Promise<Buffer>}} DiagramSession */
 
+/**
+ * Export failures must stay within the wording callers match on, so CDP details are wrapped here.
+ * @param {string} detail @returns {Error}
+ */
+const exportFailure = (detail) => new Error(`Browser raster export failed: ${detail}`);
+
+/** @param {()=>string} read @param {number} deadline @returns {Promise<number>} */
+export async function waitForDebuggingPort(read, deadline) {
+  while (Date.now() < deadline) {
+    try {
+      const value = read().split("\n")[0].trim();
+      const port = Number(value);
+      if (/^\d+$/.test(value) && Number.isInteger(port) && port > 0 && port <= 65535) return port;
+    } catch (error) {
+      const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+      if (!["EBUSY", "ENOENT", "EPERM"].includes(code)) throw exportFailure(error instanceof Error ? error.message : String(error));
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+  }
+  throw exportFailure("browser debugging port did not become readable before the initialization deadline.");
+}
+
+/**
+ * The target URL can be advertised before its execution context has finished navigating.
+ * Retry only that initialization window; action failures must propagate without replaying exports.
+ * @param {DiagramSession['evaluate']} evaluate @param {string} url @param {number} deadline
+ */
+export async function waitForDiagramReady(evaluate, url, deadline) {
+  while (Date.now() < deadline) {
+    try {
+      const ready = await evaluate(`(async()=>{if(location.href!==${JSON.stringify(url)})return false;if(document.readyState!=="complete")await new Promise(r=>window.addEventListener("load",r,{once:true}));await document.fonts.ready;await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));return true;})()`);
+      if (ready === true) return;
+    } catch (error) {
+      if (!(error instanceof Error) || !/^Browser raster export failed: (?:Execution context was destroyed|Cannot find default execution context)\.?$/.test(error.message)) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+  }
+  throw exportFailure("diagram page did not become ready before the initialization deadline.");
+}
+
+/**
+ * Chromium keeps profile files locked until its whole process tree is gone, so cleanup waits for
+ * the process instead of sleeping a fixed amount. @param {ReturnType<typeof spawn>} child @param {number} ms @returns {Promise<void>}
+ */
+const waitForExit = async (child, ms) => {
+  if (child.exitCode !== null) return;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  await new Promise((resolve) => {
+    const finish = () => { if (timer) clearTimeout(timer); child.off("exit", finish); resolve(undefined); };
+    timer = setTimeout(finish, ms);
+    child.once("exit", finish);
+  });
+};
+
 /** @template T @param {string} html @param {{theme:'light'|'dark',timeoutMs:number}} options @param {(session:DiagramSession)=>Promise<T>} action @returns {Promise<T>} */
 export async function withDiagramPage(html, options, action) {
   const browser = findBrowser();
@@ -38,26 +93,33 @@ export async function withDiagramPage(html, options, action) {
   let timer;
   try {
     const work = async () => {
-    const deadline = Date.now() + Math.min(5000, options.timeoutMs);
+    const deadline = Date.now() + Math.min(15000, options.timeoutMs);
     const portFile = path.join(profile, "DevToolsActivePort");
     while (!fs.existsSync(portFile) && Date.now() < deadline && (child.exitCode === null || child.exitCode === 0) && !childError) await new Promise((resolve) => setTimeout(resolve, 50));
-    if (!fs.existsSync(portFile)) throw new Error(`Browser raster export failed: browser did not start a debugging session${childError ? ` (${childError})` : ""}.`);
-    const port = Number(fs.readFileSync(portFile, "utf8").split("\n")[0]);
-    const pages = await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(Math.min(5000, options.timeoutMs)) })).json();
-    const target = pages.find(/** @param {{type:string}} p */ (p) => p.type === "page");
-    if (!target?.webSocketDebuggerUrl) throw new Error("Browser did not create a diagram page.");
+    if (!fs.existsSync(portFile)) throw exportFailure(`browser did not start a debugging session${childError ? ` (${childError})` : ""}.`);
+    const port = await waitForDebuggingPort(() => fs.readFileSync(portFile, "utf8"), deadline);
+    // Select the intended target first; the readiness handshake below also waits for its context.
+    /** @type {{webSocketDebuggerUrl?:string}|undefined} */
+    let target;
+    while (Date.now() < deadline) {
+      const pages = await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(Math.min(5000, options.timeoutMs)) })).json();
+      target = pages.find(/** @param {{type:string,url:string}} p */ (p) => p.type === "page" && p.url === pathToFileURL(page).href);
+      if (target) break;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    if (!target?.webSocketDebuggerUrl) throw exportFailure("browser did not create a diagram page.");
     socket = new WebSocket(target.webSocketDebuggerUrl);
     await new Promise((resolve, reject) => { socket?.addEventListener("open", resolve, { once: true }); socket?.addEventListener("error", reject, { once: true }); });
     /** @type {Map<number,{resolve:(value:Record<string,unknown>)=>void,reject:(reason:Error)=>void}>} */
     const pending = new Map();
-    socket.addEventListener("close", () => { for (const entry of pending.values()) entry.reject(new Error("Browser session closed before export completed.")); pending.clear(); });
+    socket.addEventListener("close", () => { for (const entry of pending.values()) entry.reject(exportFailure("session closed before export completed.")); pending.clear(); });
     let serial = 0;
     socket.addEventListener("message", (event) => {
       const message = JSON.parse(String(event.data));
       const entry = pending.get(message.id);
       if (!entry) return;
       pending.delete(message.id);
-      if (message.error) entry.reject(new Error(message.error.message)); else entry.resolve(message.result ?? {});
+      if (message.error) entry.reject(exportFailure(message.error.message)); else entry.resolve(message.result ?? {});
     });
     /** @param {string} method @param {Record<string,unknown>} [params] @returns {Promise<Record<string,unknown>>} */
     const call = (method, params = {}) => new Promise((resolve, reject) => { const id = ++serial; pending.set(id, { resolve, reject }); socket?.send(JSON.stringify({ id, method, params })); });
@@ -73,18 +135,19 @@ export async function withDiagramPage(html, options, action) {
       const result = await call("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, clip: { x: 0, y: 0, width, height, scale: 1 } });
       return Buffer.from(String(result.data), "base64");
     } };
-    await evaluate(`(async()=>{if(document.readyState!=="complete")await new Promise(r=>window.addEventListener("load",r,{once:true}));await document.fonts.ready;await new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r)));})()`);
+    await waitForDiagramReady(evaluate, pathToFileURL(page).href, deadline);
     return await action(session);
     };
-    return await Promise.race([work(), new Promise(/** @param {(reason:Error)=>void} reject */ (_, reject) => { timer = setTimeout(() => reject(new Error("Browser export timed out.")), options.timeoutMs); })]);
+    return await Promise.race([work(), new Promise(/** @param {(reason:Error)=>void} reject */ (_, reject) => { timer = setTimeout(() => reject(exportFailure("export timed out.")), options.timeoutMs); })]);
   } finally {
     if (timer) clearTimeout(timer);
     if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ id: 999999, method: "Browser.close" }));
-    await new Promise((resolve) => setTimeout(resolve, 120));
+    // Browser.close is graceful, so wait for the process rather than guessing with a fixed sleep:
+    // Chromium's child processes keep profile files locked until the tree is gone.
+    await waitForExit(child, 2000);
     socket?.close();
-    child.kill();
+    if (child.exitCode === null) child.kill();
     // The Chromium profile is owned by this invocation only. Windows may release locks after exit.
-    await new Promise((resolve) => setTimeout(resolve, 120));
-    try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); } catch { /* A locked temporary profile can be removed by OS cleanup. */ }
+    try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 }); } catch { /* A locked temporary profile can be removed by OS cleanup. */ }
   }
 }

package/localized/zh-CN/skills/cc-technical-diagrams/scripts/diagram-layout.mjs

@@ -0,0 +1,176 @@
+// @ts-check
+
+/** @typedef {{x:number,y:number,width:number,height:number}} Rect */
+/** @typedef {[number,number]} Point */
+/** @typedef {{code:string,id:string,message:string}} QualityIssue */
+/** @typedef {{lines:string[],width:number,height:number,fontSize:number,lineHeight:number}} TextLayout */
+/** @typedef {Rect & {id:string,label:string,sublabel:string,type:string,actor?:string,step?:string,shape?:"box"|"diamond"|"terminal"}} Box */
+
+/** @param {string} text @param {number} fontSize */
+function textWidth(text, fontSize) {
+  return [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)]
+    .reduce((sum, item) => sum + (/^[\x00-\x7f]+$/.test(item.segment) ? fontSize * 0.6 : fontSize), 0);
+}
+
+/** @param {string} text @param {number} maxWidth @param {number} [fontSize] @param {number} [lineHeight] @returns {TextLayout} */
+export function layoutText(text, maxWidth, fontSize = 14, lineHeight = 20) {
+  const limit = Math.max(fontSize, maxWidth);
+  /** @type {string[]} */
+  const lines = [];
+  for (const paragraph of text.split(/\r?\n/)) {
+    let line = "";
+    for (const { segment: word } of new Intl.Segmenter(undefined, { granularity: "word" }).segment(paragraph)) {
+      if (line && textWidth(word,fontSize) <= limit && textWidth(line+word,fontSize)>limit) {lines.push(line);line="";}
+      for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(word)) {
+      if (line && textWidth(line + segment, fontSize) > limit) {
+        lines.push(line);
+        line = "";
+      }
+      line += segment;
+      }
+    }
+    lines.push(line);
+  }
+  return { lines, width: Math.max(0, ...lines.map((line) => textWidth(line, fontSize))), height: lines.length * lineHeight, fontSize, lineHeight };
+}
+
+/** @param {Box} source @param {{width:boolean,height:boolean}} explicit */
+export function fitNodeText(source, explicit) {
+  const box = { ...source };
+  if (![box.width, box.height].every((v) => Number.isFinite(v) && v > 0)) throw new Error(`Invalid size for node "${box.id}".`);
+  const diamond = box.shape === "diamond" || box.type === "decision";
+  const semantic = ["agent", "model", "memory", "vectorstore", "graphdb", "tool", "document", "queue", "browser", "user", "gateway"].includes(box.type);
+  if (!explicit.width) box.width = Math.max(box.width, diamond ? 240 : 200);
+  const available = diamond ? box.width * 0.5 - 12 : (box.type === "queue" ? box.width - 64 : box.width - 32);
+  const main = layoutText(box.label, available);
+  const sub = layoutText(box.sublabel, available, 12, 16);
+  const header = ["database", "vectorstore"].includes(box.type) ? 30 : box.type === "queue" ? 20 : semantic ? 46 : box.actor ? 40 : 20;
+  const contentHeight = main.height + (box.sublabel ? sub.height + 6 : 0);
+  const needed = diamond ? (contentHeight + 24) * 2 : header + contentHeight + (["database", "vectorstore"].includes(box.type) ? 30 : 18);
+  if (!explicit.height) box.height = Math.max(box.height, needed, 72);
+  /** @type {QualityIssue[]} */
+  const issues = [];
+  if (box.height < needed || available < main.width) issues.push({ code: "node-text-overflow", id: box.id, message: `Node "${box.id}" has an explicit size too small for its complete text.` });
+  return { box, labels: [main, sub], issues };
+}
+
+/** @param {Rect} box @param {'top'|'right'|'bottom'|'left'} side @returns {Point} */
+export function boundaryPort(box, side) {
+  if (side === "top") return [box.x + box.width / 2, box.y];
+  if (side === "bottom") return [box.x + box.width / 2, box.y + box.height];
+  if (side === "left") return [box.x, box.y + box.height / 2];
+  return [box.x + box.width, box.y + box.height / 2];
+}
+
+/** Strict interior intersection; boundary contact is allowed. @param {Point} a @param {Point} b @param {Rect} r */
+export function segmentHits(a, b, r) {
+  let lo = 0, hi = 1;
+  for (const axis of [0, 1]) {
+    const start = axis === 0 ? r.x : r.y;
+    const end = start + (axis === 0 ? r.width : r.height);
+    const delta = b[axis] - a[axis];
+    if (Math.abs(delta) < 1e-8) {
+      if (a[axis] <= start + 1e-6 || a[axis] >= end - 1e-6) return false;
+    } else {
+      const t1 = (start - a[axis]) / delta, t2 = (end - a[axis]) / delta;
+      lo = Math.max(lo, Math.min(t1, t2)); hi = Math.min(hi, Math.max(t1, t2));
+    }
+  }
+  return hi - lo > 1e-6;
+}
+
+/** @param {Rect} a @param {Rect} b */
+export function overlaps(a, b) {
+  return Math.min(a.x + a.width, b.x + b.width) > Math.max(a.x, b.x) + 1e-6 && Math.min(a.y + a.height, b.y + b.height) > Math.max(a.y, b.y) + 1e-6;
+}
+
+/** @param {Point[]} points @returns {Point[]} */
+function simplify(points) {
+  return points.filter((p, i) => {
+    if (i && p[0] === points[i - 1][0] && p[1] === points[i - 1][1]) return false;
+    if (!i || i === points.length - 1) return true;
+    const prev = points[i - 1], next = points[i + 1];
+    return !((prev[0] === p[0] && next[0] === p[0]) || (prev[1] === p[1] && next[1] === p[1]));
+  });
+}
+
+/** @param {Rect & {id:string}} from @param {Rect & {id:string}} to @param {Rect[]} obstacles @param {Point[][]} occupied @param {Point[]} [waypoints] */
+export function routeConnector(from, to, obstacles, occupied, waypoints) {
+  const horizontal = Math.abs(to.x - from.x) >= Math.abs(to.y - from.y);
+  const forward = horizontal ? to.x >= from.x : to.y >= from.y;
+  const start = boundaryPort(from, horizontal ? (forward ? "right" : "left") : (forward ? "bottom" : "top"));
+  const end = boundaryPort(to, horizontal ? (forward ? "left" : "right") : (forward ? "top" : "bottom"));
+  /** @type {QualityIssue[]} */
+  const issues = [];
+  if (waypoints) {
+    const points = [start, ...waypoints, end];
+    if (points.some((p, i) => i > 0 && obstacles.some((r) => segmentHits(points[i - 1], p, r)))) issues.push({ code: "route-obstructed", id: `${from.id}-${to.id}`, message: "Explicit waypoints cross a non-endpoint node." });
+    return { points, issues };
+  }
+  if (from.id === to.id) {
+    const x = from.x + from.width + 40 + occupied.length * 4;
+    return { points: /** @type {Point[]} */ ([[from.x + from.width, from.y + from.height / 3], [x, from.y + from.height / 3], [x, from.y + from.height * 2 / 3], [from.x + from.width, from.y + from.height * 2 / 3]]), issues };
+  }
+  const padded = obstacles.map((r) => ({ x: r.x - 12, y: r.y - 12, width: r.width + 24, height: r.height + 24 }));
+  const xSet = new Set([start[0], end[0], 28]), ySet = new Set([start[1], end[1], 28]);
+  for (const r of [...padded, from, to]) { xSet.add(r.x - 16); xSet.add(r.x + r.width + 16); ySet.add(r.y - 16); ySet.add(r.y + r.height + 16); }
+  for (const route of occupied) for (const [x, y] of route) { xSet.add(x - 16); xSet.add(x + 16); ySet.add(y - 16); ySet.add(y + 16); }
+  const xs = [...xSet].filter((x) => x >= 24).sort((a, b) => a - b), ys = [...ySet].filter((y) => y >= 24).sort((a, b) => a - b);
+  if (xs.length > 128 || ys.length > 128) return { points: [start, end], issues: [{ code: "route-unresolved", id: `${from.id}-${to.id}`, message: "Routing grid exceeded its bounded search budget." }] };
+  const nx = xs.length, ny = ys.length;
+  const startId = ys.indexOf(start[1]) * nx + xs.indexOf(start[0]), endId = ys.indexOf(end[1]) * nx + xs.indexOf(end[0]);
+  /** @param {number} id @returns {Point} */
+  const point = (id) => [xs[id % nx], ys[Math.floor(id / nx)]];
+  /** @type {Array<{node:number,dir:number,cost:number,key:string}>} */
+  const pending = [{ node: startId, dir: 0, cost: 0, key: `${startId}:0` }];
+  const best = new Map([[`${startId}:0`, 0]]), previous = new Map();
+  let finish = "";
+  while (pending.length) {
+    pending.sort((a, b) => a.cost - b.cost || a.node - b.node || a.dir - b.dir);
+    const current = pending.shift();
+    if (!current || current.cost !== best.get(current.key)) continue;
+    if (current.node === endId) { finish = current.key; break; }
+    const ix = current.node % nx, iy = Math.floor(current.node / nx);
+    for (const [dx, dy] of [[-1, 0], [1, 0], [0, -1], [0, 1]]) {
+      if (ix + dx < 0 || ix + dx >= nx || iy + dy < 0 || iy + dy >= ny) continue;
+      const next = (iy + dy) * nx + ix + dx, a = point(current.node), b = point(next);
+      if ([...padded, from, to].some((r) => segmentHits(a, b, r))) continue;
+      const dir = dx ? 1 : 2;
+      let penalty = 0;
+      for (const route of occupied) for (let i = 1; i < route.length; i++) {
+        const p = route[i - 1], q = route[i];
+        if ((a[0] === b[0] && p[0] === q[0] && a[0] === p[0] && Math.min(b[1], a[1]) < Math.max(p[1], q[1]) && Math.max(b[1], a[1]) > Math.min(p[1], q[1])) || (a[1] === b[1] && p[1] === q[1] && a[1] === p[1] && Math.min(b[0], a[0]) < Math.max(p[0], q[0]) && Math.max(b[0], a[0]) > Math.min(p[0], q[0]))) penalty += 80;
+      }
+      const cost = current.cost + Math.abs(b[0] - a[0]) + Math.abs(b[1] - a[1]) + (current.dir && current.dir !== dir ? 24 : 0) + penalty;
+      const key = `${next}:${dir}`;
+      if (cost < (best.get(key) ?? Infinity)) { best.set(key, cost); previous.set(key, current.key); pending.push({ node: next, dir, cost, key }); }
+    }
+  }
+  if (!finish) return { points: [start, end], issues: [{ code: "route-unresolved", id: `${from.id}-${to.id}`, message: "No obstacle-free route exists without moving explicit nodes." }] };
+  /** @type {Point[]} */
+  const route = [];
+  for (let key = finish; key; key = previous.get(key)) route.unshift(point(Number(key.split(":")[0])));
+  return { points: simplify(route), issues };
+}
+
+/** @param {Point[]} points @param {TextLayout} layout @param {Rect[]} obstacles @param {Point[][]} [routes] */
+export function placeEdgeLabel(points, layout, obstacles, routes = []) {
+  const lengths = points.slice(1).map((p, i) => Math.hypot(p[0] - points[i][0], p[1] - points[i][1]));
+  let remaining = lengths.reduce((a, b) => a + b, 0) / 2;
+  let cx = points[0][0], cy = points[0][1];
+  for (let i = 0; i < lengths.length; i++) {
+    if (remaining <= lengths[i]) {
+      const ratio = lengths[i] ? remaining / lengths[i] : 0;
+      cx = points[i][0] + (points[i + 1][0] - points[i][0]) * ratio;
+      cy = points[i][1] + (points[i + 1][1] - points[i][1]) * ratio;
+      break;
+    }
+    remaining -= lengths[i];
+  }
+  let rect = { x: cx - layout.width / 2, y: cy - layout.height - 12, width: layout.width, height: layout.height };
+  for (const offset of [12,24,36,52,72,96]) for (const direction of ["above","below","left","right"]) {
+    const candidate = direction === "above" ? {...rect,y:cy-layout.height-offset} : direction === "below" ? {...rect,y:cy+offset} : direction === "left" ? {...rect,x:cx-layout.width-offset,y:cy-layout.height/2} : {...rect,x:cx+offset,y:cy-layout.height/2};
+    if (candidate.x >= 24 && candidate.y >= 24 && !obstacles.some((r) => overlaps(candidate, r)) && !routes.some(route=>route.slice(1).some((point,index)=>segmentHits(route[index],point,{x:candidate.x-4,y:candidate.y-4,width:candidate.width+8,height:candidate.height+8})))) return { rect: candidate, issues: /** @type {QualityIssue[]} */ ([]) };
+  }
+  return { rect, issues: [{ code: "edge-label-collision", id: "edge", message: "No free label position near route midpoint." }] };
+}