@bovinphang/craft-common 0.0.0-stage → 1.0.1

package/skills/cc-technical-diagrams/assets/quality-examples/workflow.json

@@ -0,0 +1,98 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Order approval and recovery"
+  },
+  "lanes": [
+    {
+      "id": "user",
+      "label": "User submission"
+    },
+    {
+      "id": "ops",
+      "label": "Approval and handling"
+    },
+    {
+      "id": "sys",
+      "label": "System execution"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "start",
+      "lane": "user",
+      "col": 0,
+      "label": "Submit order request",
+      "type": "start"
+    },
+    {
+      "id": "check",
+      "lane": "ops",
+      "col": 1,
+      "label": "Check order completeness and approval eligibility",
+      "type": "decision"
+    },
+    {
+      "id": "approve",
+      "lane": "ops",
+      "col": 2,
+      "label": "Review manually and record the decision",
+      "type": "backend"
+    },
+    {
+      "id": "retry",
+      "lane": "user",
+      "col": 1,
+      "label": "Add missing evidence and resubmit",
+      "type": "waiting"
+    },
+    {
+      "id": "save",
+      "lane": "sys",
+      "col": 3,
+      "label": "Save approval and notify the applicant asynchronously",
+      "type": "database"
+    },
+    {
+      "id": "done",
+      "lane": "sys",
+      "col": 4,
+      "label": "Completed",
+      "type": "success"
+    }
+  ],
+  "edges": [
+    {
+      "from": "start",
+      "to": "check",
+      "label": "Submit for review"
+    },
+    {
+      "from": "check",
+      "to": "approve",
+      "label": "Complete information"
+    },
+    {
+      "from": "check",
+      "to": "retry",
+      "label": "More evidence needed",
+      "variant": "dashed"
+    },
+    {
+      "from": "retry",
+      "to": "check",
+      "label": "Review again"
+    },
+    {
+      "from": "approve",
+      "to": "save",
+      "label": "Approved"
+    },
+    {
+      "from": "save",
+      "to": "done",
+      "label": "Notification sent"
+    }
+  ]
+}

package/skills/cc-technical-diagrams/assets/quality-examples/workflow.mmd

@@ -0,0 +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])

package/skills/cc-technical-diagrams/references/diagram-workflows.md

@@ -0,0 +1,81 @@
+# Diagram Workflows
+
+## Source selection
+
+| Diagram type | Preferred source | QA focus |
+| ------------ | ---------------- | -------- |
+| ER diagram | Mermaid ER, DBML, Graphviz, SVG | Cardinality labels, table names, key fields, crossing relations. |
+| UML class | Mermaid class, PlantUML, Graphviz | Inheritance direction, method/property wrapping, package grouping. |
+| Sequence | Mermaid sequence, PlantUML | Lifeline order, activation spans, async/return arrows, message text. |
+| Technical architecture | draw.io, Mermaid/C4, HTML `architecture` IR, SVG/HTML | Layer grouping, trust boundaries, data flow direction, legends. |
+| Agent / memory architecture | HTML `architecture` IR with semantic node types and flow arrows, SVG/HTML, draw.io | Read/write path separation, tool-call loops, memory tiers, retrieval labels, flow legend. |
+| ML / deep learning | SVG/HTML/canvas | Tensor shapes, layer order, branch joins, repeated blocks, annotations. |
+| Flowchart / process workflow | Mermaid flowchart, HTML `workflow` IR, SVG, draw.io | Decision labels, terminal states, loop-back readability, connector spacing, exception path clarity. |
+| Live session sketch | Interactive local browser server | Incremental reveal, session isolation, readable labels after manual dragging, export handoff. |
+
+## Interactive live diagrams
+
+Use the live route when the diagram is part of the conversation and the user benefits from seeing structure appear as it is generated. It is best for flow sketches, architecture drafts, short mind-map-like decompositions, and quick walkthroughs that may be dragged or relabeled before export.
+
+Run the local server with:
+
+```bash
+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.
+
+Supported commands are `init`, `node`, `edge`, `container`, `remove`, `clear`, `layout`, `title`, and `export`. Supported node types are `terminal`, `terminal-end`, `process`, `decision`, `service`, `database`, `success`, `error`, and `container`.
+
+Use `/export?s=session-id&format=json`, `svg`, or `drawio` for server-side source handoff. Use the browser toolbar for PNG export. If the local server cannot start, use Mermaid, SVG, or HTML technical diagrams instead of blocking the user.
+
+## Minimum source manifest
+
+When the rendering path allows it, save a layout manifest next to the PNG:
+
+```json
+{
+  "canvas": { "width": 1280, "height": 720 },
+  "boxes": [
+    { "id": "api", "x": 80, "y": 120, "width": 220, "height": 96, "label": "API Gateway" }
+  ],
+  "connectors": [
+    { "id": "api-db", "from": "api", "to": "db", "points": [[300, 168], [560, 168]] }
+  ]
+}
+```
+
+Coordinates are PNG pixel coordinates after export. Boxes should cover visible label/node bounds, not just the center point.
+
+## Diagram repair playbook
+
+- **Overlapping nodes:** increase rank/column spacing, split clusters, or move low-priority annotations into a legend.
+- **Truncated labels:** widen the node, add manual line breaks, preserve the full text, and adjust source layout.
+- **Connector through labels:** add waypoints, route orthogonally around boxes, or move labels above the segment.
+- **Connector stacking:** separate parallel edges with different waypoints or bundle them with a shared labeled bus.
+- **Edge clipping:** increase outer padding or export viewBox/canvas size.
+- **Unreadable dense graph:** split into overview plus detail diagrams instead of shrinking everything.
+- **Ambiguous arrow meaning:** add `flow` and a concise label rather than relying on color alone.
+
+## Architecture diagrams
+
+Use HTML `architecture` IR when the user wants a browser-ready single file with explicit system topology, groups, trust boundaries, data flows, and PNG QA. Use draw.io when the diagram must preserve official vendor shapes, diagrams.net editing, or long-term manual ownership. Use Mermaid/C4 when the diagram should live primarily in Markdown or text documentation.
+
+For agent, memory, RAG, tool-call, or multi-agent diagrams, use semantic architecture node types (`agent`, `model`, `memory`, `vectorstore`, `graphdb`, `tool`, `document`, `queue`, `browser`, `user`, `gateway`) instead of generic boxes when the shape helps explain the system. Use `flow` values (`control`, `data`, `read`, `write`, `async`, `feedback`) so read paths, write paths, events, and reasoning loops are visually distinct. Add `visual.style` only after the structure is clear.
+
+For UML coverage, route class, ER, state-machine, activity, and sequence needs to deterministic sources first: Mermaid, PlantUML, HTML technical diagrams, SVG, or draw.io. Prefer draw.io when future manual editing or official notation libraries matter; prefer HTML/SVG when browser-ready handoff and PNG QA matter.
+
+## 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 `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
+
+Prefer exporting at 2x scale for raster PNGs, then downsample only if text remains crisp. Keep the editable source committed or attached wherever future diagram changes are expected.
+
+
+## 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/skills/cc-technical-diagrams/references/html-technical-diagrams.md

@@ -0,0 +1,243 @@
+# HTML Technical Diagrams
+
+Use this route when a technical diagram should be easy to open in a browser, share as one file, switch dark/light themes, and export from the browser after visual QA.
+
+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 | `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 |
+
+## Supported Diagram Intents
+
+- `architecture`: system topology, system blueprints, deployment topology, cloud regions, trust boundaries, clients, gateways, services, data stores, event buses, auth flows, agent runtime maps, memory or recall overview diagrams, before/after architecture comparisons, and infrastructure overview diagrams.
+- `workflow`: ownership lanes, process maps, approval gates, automation runs, exception paths, cyclical loops, runbooks, CI/CD, incident response, tool calls, and request lifecycles.
+- `sequence`: participants over time, API call chains, cache fallback, auth checks, async traces, and return messages.
+- `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 `cc-drawio-studio` instead when the priority is `.drawio` source, official vendor icons, diagrams.net manual editing, or complex auto-layout.
+
+## Themed Semantic Diagrams
+
+Use `visual.style` when the same JSON source needs a clearer delivery tone without changing its model: `default`, `terminal`, `blueprint`, `minimal`, `glass`, `warm`, `openai`, or `editorial-dark`.
+
+For agent, memory, and AI workflow maps, prefer architecture nodes with semantic `type` values:
+
+- Actors and entry points: `user`, `browser`, `gateway`.
+- Intelligence and orchestration: `agent`, `model`, `tool`.
+- Memory and knowledge: `memory`, `vectorstore`, `graphdb`, `document`.
+- Runtime movement: `queue`, `messagebus`, `backend`, `external`.
+
+Use connection `flow` values when arrows need meaning beyond visual direction:
+
+- `control`: orchestration, policy, trigger, or command.
+- `data`: request payloads, documents, embeddings, facts, or responses.
+- `read`: retrieval from memory or stores.
+- `write`: persistence, indexing, notes, or memory updates.
+- `async`: evented or queued work.
+- `feedback`: loops, retries, refinement, or reasoning cycles.
+
+When two or more flow types are present, the renderer emits a flow legend automatically. Keep arrow labels short and use `waypoints` to route around dense groups, title labels, and node interiors.
+
+## System Blueprint Workflow
+
+Use the architecture route for presentation-ready system blueprints, deployment topology, integration maps, agent runtime views, memory or recall maps, and before/after architecture comparisons. First extract a compact system model, then draw:
+
+- Entry surfaces: browsers, mobile clients, CLIs, webhooks, schedulers, or agent/session entry points.
+- Application layer: gateways, frontend apps, backend services, workers, orchestration, runtime hosts, and tool adapters.
+- Data layer: databases, object stores, caches, vector stores, queues, event buses, logs, and analytics stores.
+- External dependencies: identity providers, AI models, payment/email services, SaaS APIs, cloud services, design tools, or runtime connectors.
+- Identity and trust boundaries: auth, permissions, PII zones, tenant boundaries, private networks, secret stores, and policy checks.
+- Key flows: request/control flow, data flow, event flow, deployment flow, recall/memory flow, or before/after migration flow.
+
+Keep the first blueprint readable:
+
+- Show 4-10 primary nodes and collapse low-value files, classes, or endpoints into grouped nodes.
+- Use 1-3 group boundaries for layers, trust zones, runtime environments, or ownership domains.
+- Include a short title and subtitle that work when the file is shared outside the original conversation.
+- Use a legend or up to three summary cards for runtime, data, trust, risks, inputs, or outcomes.
+- Prefer semantic color roles over decorative styling, and split into multiple diagrams when connectors or labels become dense.
+
+For README or stakeholder handoff, keep the JSON IR and HTML as the editable source, then export SVG/PNG/JPG artifacts:
+
+```bash
+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.
+
+## JSON IR
+
+All modes require:
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Release Workflow",
+    "subtitle": "PR to production"
+  }
+}
+```
+
+Mode-specific minimum fields:
+
+- `architecture`: `nodes`, `connections`; optional `groups`, `legend`, and `summary`.
+- `workflow`: `lanes`, `nodes`, `edges`; optional `summary`.
+- `sequence`: `participants`, `messages`.
+- `dataflow`: `stages`, `nodes`, `flows`.
+- `lifecycle`: `lanes`, `states`, `transitions`.
+
+IDs must start with a letter and use only letters, numbers, `_`, and `-`. Keep labels short enough to read inside nodes; put long explanation in surrounding prose instead of the diagram.
+
+## Process Workflow IR
+
+Workflow mode is for ordered processes where ownership, decisions, branches, and loop-backs matter more than exact infrastructure topology. Use lanes for actors or systems, nodes for steps, and edges for outcomes. Nodes still support explicit `col` placement so authors can control reading order without relying on a hidden auto-layout engine.
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Procurement Approval",
+    "subtitle": "Request to payment"
+  },
+  "lanes": [
+    { "id": "requester", "label": "Requester" },
+    { "id": "system", "label": "System" },
+    { "id": "manager", "label": "Manager" }
+  ],
+  "nodes": [
+    { "id": "start", "lane": "requester", "col": 0, "type": "start", "label": "Submit Request", "actor": "Employee" },
+    { "id": "classify", "lane": "system", "col": 1, "type": "active", "label": "Classify Spend", "actor": "Policy Engine", "sublabel": "auto rules" },
+    { "id": "review", "lane": "manager", "col": 2, "type": "decision", "label": "Approved?", "step": "A" },
+    { "id": "pay", "lane": "system", "col": 3, "type": "success", "label": "Issue Payment" },
+    { "id": "reject", "lane": "requester", "col": 3, "type": "failure", "label": "Return Request" }
+  ],
+  "edges": [
+    { "from": "start", "to": "classify", "label": "intake", "variant": "emphasis" },
+    { "from": "classify", "to": "review", "label": "policy result" },
+    { "from": "review", "to": "pay", "label": "yes", "variant": "emphasis" },
+    { "from": "review", "to": "reject", "label": "no", "variant": "return", "waypoints": [[650, 396], [520, 396]] }
+  ],
+  "summary": [
+    { "title": "Inputs", "type": "active", "items": ["Purchase request", "Policy threshold"] },
+    { "title": "Outcomes", "type": "success", "items": ["Payment issued", "Requester notified"] }
+  ]
+}
+```
+
+Workflow node fields:
+
+- `type`: use `start`, `active`, `waiting`, `decision`, `success`, `failure`, or `external` for process semantics.
+- `actor`: optional short owner or system label above the node.
+- `step`: optional displayed step marker. If omitted, workflow nodes receive sequential markers automatically.
+- `sublabel`, `width`, `height`, and `yOffset`: optional readability adjustments for dense lanes.
+
+Workflow edge fields:
+
+- `variant`: use `emphasis` for happy paths, `return` or `dashed` for loop-backs and rework, and `security` only for trust or policy checks.
+- `waypoints`: optional `[x, y]` points for exception paths, cross-row links, or loops that should avoid labels and nodes.
+
+Use `summary` for compact process metadata such as prerequisites, inputs/outputs, or tools. Keep long explanations outside the SVG so labels remain readable.
+
+## Architecture IR
+
+Architecture mode uses explicit coordinates because system diagrams often need intentional placement, boundaries, and trust zones:
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "SaaS Architecture",
+    "subtitle": "Browser-ready infrastructure overview"
+  },
+  "visual": {
+    "style": "blueprint"
+  },
+  "groups": [
+    { "id": "cloud", "label": "Cloud region", "type": "cloud", "x": 170, "y": 50, "width": 620, "height": 280 }
+  ],
+  "nodes": [
+    { "id": "web", "label": "Web App", "type": "frontend", "x": 48, "y": 160, "sublabel": "React" },
+    { "id": "api", "label": "API Gateway", "type": "cloud", "x": 230, "y": 160, "group": "cloud" },
+    { "id": "svc", "label": "App Service", "type": "backend", "x": 420, "y": 160, "group": "cloud" },
+    { "id": "db", "label": "PostgreSQL", "type": "database", "x": 620, "y": 160, "group": "cloud" }
+  ],
+  "connections": [
+    { "from": "web", "to": "api", "label": "HTTPS", "variant": "emphasis" },
+    { "from": "api", "to": "svc", "label": "REST" },
+    { "from": "svc", "to": "db", "label": "SQL" }
+  ],
+  "summary": [
+    { "title": "Runtime", "type": "backend", "items": ["API and worker services", "Managed relational data"] }
+  ]
+}
+```
+
+Supported node and group types include `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`, `agent`, `model`, `memory`, `vectorstore`, `graphdb`, `tool`, `document`, `queue`, `browser`, `user`, and `gateway`. Connections support the standard variants `default`, `emphasis`, `security`, `dashed`, and `return`; architecture connections may also include `flow`. Add `waypoints` as `[[x, y], ...]` when a connection needs to route around boundaries or labels.
+
+Architecture output includes an automatic legend unless `legend` is set to `false`. A custom legend can be supplied as `{ "label": "...", "type": "..." }` items. `summary` renders up to three cards below the SVG and is not included in the layout manifest, so PNG QA focuses on the diagram itself.
+
+## Architecture Layout Rules
+
+- Draw groups as broad boundaries around components, not as decorative panels.
+- Keep legends below or outside all boundaries; increase the coordinates and view area rather than squeezing content.
+- Use `messagebus` nodes for event buses and place them in the gap between services.
+- Use `security` connections for auth, token, policy, or trust-boundary flows.
+- Prefer `waypoints` over dense crossing lines when gateways fan out to several services.
+- Split the diagram when the overview needs more than one dense cluster or when label readability depends on shrinking text.
+
+## Render Command
+
+```bash
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs \
+  --input diagram.json \
+  --output diagram.html \
+  --type architecture \
+  --manifest diagram.layout.json
+```
+
+The generated HTML is self-contained and includes:
+
+- Inline SVG.
+- CSS-variable dark/light theme.
+- Browser controls for theme toggle, SVG download, and print/PDF.
+- Optional layout manifest for PNG QA.
+
+## QA and Repair
+
+After exporting a PNG from the browser, run:
+
+```bash
+node skills/cc-technical-diagrams/scripts/png-qa.mjs \
+  --png diagram.png \
+  --manifest diagram.layout.json \
+  --format markdown
+```
+
+Repair the source JSON or rendering dimensions rather than editing pixels:
+
+- Overlap: split dense lanes or add rows/lanes/stages.
+- Truncated label: wrap complete labels, preserve text, or widen nodes.
+- Connector through label: reduce edge labels or separate nearby nodes.
+- Dense flow: split into overview and detail diagrams.
+- Edge clipping: increase output space or simplify the path.
+
+## Delivery Notes
+
+Deliver the `.html` source together with any exported SVG/PNG/JPG requested by the user. Report the route used, source file, exported file, QA result, and any naming or domain assumptions that still need human confirmation.
+
+
+## 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/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/skills/cc-technical-diagrams/scripts/diagram-browser.mjs

@@ -0,0 +1,153 @@
+// @ts-check
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export function findBrowser() {
+  const candidates = [process.env.FEC_BROWSER_PATH,
+    "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Microsoft/Edge/Application/msedge.exe",
+    "C:/Program Files/Google/Chrome/Application/chrome.exe",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "google-chrome", "chromium", "chromium-browser", "msedge", "brave-browser", "vivaldi"];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (path.isAbsolute(candidate) ? fs.existsSync(candidate) : spawnSync(candidate, ["--version"], { timeout: 5000, windowsHide: true, stdio: "ignore" }).status === 0) return candidate;
+  }
+  return null;
+}
+
+/** @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();
+  if (!browser) throw new Error("PNG/JPG export requires a local Chromium browser. Export SVG instead, or install a Chromium browser and rerun this command.");
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fec-diagram-browser-"));
+  const page = path.join(dir, "diagram.html"), profile = path.join(dir, "profile");
+  fs.writeFileSync(page, html);
+  const child = spawn(browser, ["--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check", "--hide-scrollbars", "--remote-debugging-port=0", "--remote-allow-origins=http://localhost", `--user-data-dir=${profile}`, pathToFileURL(page).href], { windowsHide: true, stdio: "ignore" });
+  let childError = "";
+  child.on("error", (error) => { childError = error.message; });
+  /** @type {WebSocket | undefined} */
+  let socket;
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  try {
+    const work = async () => {
+    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 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(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(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 })); });
+    /** @param {string} expression */
+    const evaluate = async (expression) => {
+      const result = await call("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+      if (result.exceptionDetails) throw new Error(`Diagram evaluation failed: ${JSON.stringify(result.exceptionDetails)}`);
+      return /** @type {{value?:unknown}} */ (result.result).value;
+    };
+    /** @type {DiagramSession} */
+    const session = { evaluate, screenshot: async (width, height, scale = 1) => {
+      await call("Emulation.setDeviceMetricsOverride", { width: Math.ceil(width), height: Math.ceil(height), deviceScaleFactor: scale, mobile: false });
+      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 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(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" }));
+    // 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();
+    if (child.exitCode === null) child.kill();
+    // The Chromium profile is owned by this invocation only. Windows may release locks after exit.
+    try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 }); } catch { /* A locked temporary profile can be removed by OS cleanup. */ }
+  }
+}