@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/skills/{fec-image-generation → cc-technical-diagrams}/assets/quality-examples/README.md

@@ -3,12 +3,12 @@
 The JSON fixtures cover sequence self calls, workflow decisions and loops, and architecture groups with reverse/data/async edges. The Mermaid sources are equivalent text-first examples for standard sequence/workflow rendering. Preserve their labels and relationships when changing layout.
 
 ```sh
-node skills/fec-image-generation/scripts/tech-diagram-render.mjs --input skills/fec-image-generation/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
-node skills/fec-image-generation/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/fec-image-generation/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
-node skills/fec-image-generation/scripts/mermaid-render.mjs --input skills/fec-image-generation/assets/quality-examples/sequence.mmd --output sequence.svg --report sequence.render.json
+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
 ```
 
-Use a local Chromium browser for PNG; set FEC_BROWSER_PATH to its executable when detection fails. Mermaid needs an already installed mmdc; no automatic install or CDN is used. Missing Mermaid must be recorded as unavailable and the HTML route selected. Architecture editing uses the existing fec-drawio-studio skill when available, otherwise the JSON/HTML fixture. Graphviz is optional for dense topology and is not installed automatically.
+Use a local Chromium browser for PNG; set FEC_BROWSER_PATH to its executable when detection fails. Mermaid needs an already installed mmdc; no automatic install or CDN is used. Missing Mermaid must be recorded as unavailable and the HTML route selected. Architecture editing uses the existing cc-drawio-studio skill when available, otherwise the JSON/HTML fixture. Graphviz is optional for dense topology and is not installed automatically.
 
 Inspect final PNGs at intended reading size. Check node text against shape interiors, edge labels against arrowheads, branch/return directions, loop visibility, group boundaries and light/dark contrast. Run at 1x and 2x and inspect both. Geometry QA is evidence, not a substitute for visual review. Small explicit node sizes, overlapping explicit coordinates or obstructed explicit waypoints are reported; change the source with user intent preserved. Limit automatic source repairs to two rounds (five only when requested), and report partial acceptance if unresolved.

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

@@ -1,21 +1,21 @@
-sequenceDiagram
- participant Web as Browser client
- participant API as Order service API
- participant DB as Persistent database
- Web->>API: Query order details and current payment status
- API->>API: Validate identity and order access
- API->>DB: Cache miss: read order records
- DB-->>API: Return order records and payment status
- API-->>Web: Return results and update the page
-
- activate API
- alt Cache hit
- API-->>Web: Return cached result
- else Cache miss
- loop Retry failed query
- API->>DB: Read records
- DB-->>API: Return result
- end
- end
- API-)Web: Async update notification
- deactivate API
+sequenceDiagram
+ participant Web as Browser client
+ participant API as Order service API
+ participant DB as Persistent database
+ Web->>API: Query order details and current payment status
+ API->>API: Validate identity and order access
+ API->>DB: Cache miss: read order records
+ DB-->>API: Return order records and payment status
+ API-->>Web: Return results and update the page
+
+ activate API
+ alt Cache hit
+ API-->>Web: Return cached result
+ else Cache miss
+ loop Retry failed query
+ API->>DB: Read records
+ DB-->>API: Return result
+ end
+ end
+ API-)Web: Async update notification
+ deactivate API

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

@@ -1,7 +1,7 @@
-flowchart TD
- A([Submit order request]) --> B{Check order completeness and approval eligibility}
- B -->|Complete information| C[Review manually and record the decision]
- B -->|More evidence needed| D[Add missing evidence and resubmit]
- D -->|Review again| B
- C -->|Approved| E[(Save approval and notify the applicant asynchronously)]
- E -->|Notification sent| F([Completed])
+flowchart TD
+ A([Submit order request]) --> B{Check order completeness and approval eligibility}
+ B -->|Complete information| C[Review manually and record the decision]
+ B -->|More evidence needed| D[Add missing evidence and resubmit]
+ D -->|Review again| B
+ C -->|Approved| E[(Save approval and notify the applicant asynchronously)]
+ E -->|Notification sent| F([Completed])

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

@@ -20,7 +20,7 @@ Use the live route when the diagram is part of the conversation and the user ben
 Run the local server with:
 
 ```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
 ```
 
 Open `http://127.0.0.1:6100/?s=meaningful-session-id`, then send commands to `/cmd?s=meaningful-session-id`. Always use a unique session id for each diagram. Start with `init`, add nodes before edges, and keep each command small enough that the browser can update incrementally.
@@ -67,7 +67,7 @@ For UML coverage, route class, ER, state-machine, activity, and sequence needs t
 
 ## Process workflows
 
-Use HTML `workflow` IR when the user wants a browser-ready process map, approval flow, automation runbook, incident workflow, or cyclical operating loop with lanes, numbered steps, actors, decisions, exception paths, and summary cards. Use `fec-drawio-studio` instead when the workflow must remain a `.drawio` file for diagrams.net editing, official shape libraries, manual swimlane maintenance, or stakeholder edits after handoff.
+Use HTML `workflow` IR when the user wants a browser-ready process map, approval flow, automation runbook, incident workflow, or cyclical operating loop with lanes, numbered steps, actors, decisions, exception paths, and summary cards. Use `cc-drawio-studio` instead when the workflow must remain a `.drawio` file for diagrams.net editing, official shape libraries, manual swimlane maintenance, or stakeholder edits after handoff.
 
 ## Export guidance
 
@@ -76,6 +76,6 @@ Prefer exporting at 2x scale for raster PNGs, then downsample only if text remai
 
 ## Quality delivery contract
 
-Prefer local Mermaid for standard sequence/workflow diagrams, reuse fec-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse cc-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
 
 The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

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

@@ -7,7 +7,7 @@ This route complements, but does not replace, other diagram sources:
 | Need | Prefer |
 | ---- | ------ |
 | Small markdown-maintained diagram | Mermaid, Graphviz, or SVG |
-| Editable source for future manual changes | `fec-drawio-studio` and `.drawio` |
+| Editable source for future manual changes | `cc-drawio-studio` and `.drawio` |
 | Browser-ready themed technical diagram | HTML technical diagram route |
 | Raster-first visual, poster, concept art, or image edit | Image generation or editing route |
 
@@ -19,7 +19,7 @@ This route complements, but does not replace, other diagram sources:
 - `dataflow`: sources, ingest, processing, storage, consumers, PII boundaries, governance, analytics, and lineage.
 - `lifecycle`: object states, terminal states, retries, waits, cancellation, timeout, deployment or order status transitions.
 
-Use the `architecture` mode for browser-ready overview diagrams with explicit coordinates. Use `fec-drawio-studio` instead when the priority is `.drawio` source, official vendor icons, diagrams.net manual editing, or complex auto-layout.
+Use the `architecture` mode for browser-ready overview diagrams with explicit coordinates. Use `cc-drawio-studio` instead when the priority is `.drawio` source, official vendor icons, diagrams.net manual editing, or complex auto-layout.
 
 ## Themed Semantic Diagrams
 
@@ -65,8 +65,8 @@ Keep the first blueprint readable:
 For README or stakeholder handoff, keep the JSON IR and HTML as the editable source, then export SVG/PNG/JPG artifacts:
 
 ```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
 ```
 
 Raster export uses an existing Chromium-family browser when available. If the environment cannot rasterize SVG, deliver the generated HTML/SVG and state that PNG/JPG export needs a local browser.
@@ -198,7 +198,7 @@ Architecture output includes an automatic legend unless `legend` is set to `fals
 ## Render Command
 
 ```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 @@ The generated HTML is self-contained and includes:
 After exporting a PNG from the browser, run:
 
 ```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 @@ Deliver the `.html` source together with any exported SVG/PNG/JPG requested by t
 
 ## Quality delivery contract
 
-Prefer local Mermaid for standard sequence/workflow diagrams, reuse fec-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse cc-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
 
 The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

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

@@ -0,0 +1,37 @@
+# PNG QA And Autofix
+
+## Loop
+
+1. Export PNG from the editable source or image workflow.
+2. Inspect the PNG visually.
+3. Run `png-qa.mjs` with a manifest when available.
+4. Convert each issue into source, prompt, or layout changes.
+5. Repeat for 2 rounds by default, up to 5 when the user asks for more repair attempts.
+
+## Issue mapping
+
+| Issue | Repair |
+| ----- | ------ |
+| `blank-image` | Check export target, renderer errors, hidden layers, transparent fill, or failed image generation. |
+| `edge-clipping` | Add canvas padding, expand SVG viewBox, reduce subject scale, or export a larger frame. |
+| `box-overlap` | Increase spacing, reflow to grid/layers, split clusters, or wrap complete labels. |
+| `box-out-of-bounds` | Move the node inside canvas or increase canvas dimensions. |
+| `label-overflow` | Wrap text, widen the box, preserve complete copy, and increase font/container size together. |
+| `connector-through-label` | Add waypoints around boxes, move labels, or use orthogonal routing. |
+| `connector-stacking` | Offset parallel connectors or replace repeated lines with a labeled grouped path. |
+| `manifest-canvas-mismatch` | Regenerate the manifest from final export dimensions. |
+
+## Manifest quality
+
+The helper can only reason about overlaps and connectors when the manifest coordinates match the exported PNG. If the manifest is stale, repair the manifest first, then rerun QA.
+
+## Reporting
+
+Report the number of QA rounds and the final issue list. If issues remain because the source renderer cannot expose layout coordinates, say which checks were image-only and which require manual visual review.
+
+
+## Quality delivery contract
+
+Prefer local Mermaid for standard sequence/workflow diagrams, reuse cc-drawio-studio for manually editable architecture, and optionally use Graphviz for dense topology. Fall back to compatible JSON/HTML if local tools are missing, without automatic installation/downloads. Preview, standalone SVG and PNG share source theme styles; export with `--theme light|dark`. PNG export waits for fonts and measures text; use `--manifest source.layout.json --output-manifest image.actual.json` for scaled pixel coordinates. QA must read the actual manifest, not reuse estimated coordinates unchanged for a 2x PNG.
+
+The extended manifest retains canvas/boxes/connectors and adds coordinateSpace, scale, measurement, groups, labels and issues. Group containment is not node overlap. New checks include node-text-overflow, label-content-loss, label-out-of-bounds, edge-label-collision, text-overlap and degenerate-connector. Legacy manifests retain estimated checks. Diagnose constrained explicit sizes/waypoints without dropping text, changing relationships or silently moving coordinates. Increasing export resolution cannot fix source overflow. Visually review the final PNG and record tool availability/version, theme, scale, repair rounds and remaining defects; report partial acceptance when unresolved.

package/{localized/zh-CN/skills/fec-image-generation → 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/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." }] };
+}