@bovinphang/frontend-craft 2.8.0 → 3.0.0

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

@@ -0,0 +1,14 @@
+# Diagram quality examples
+
+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/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 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/cc-technical-diagrams/assets/quality-examples/architecture.json

@@ -0,0 +1,121 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Platform layers and trust boundaries"
+  },
+  "visual": {
+    "style": "minimal"
+  },
+  "groups": [
+    {
+      "id": "private",
+      "label": "Trusted network / business and data services",
+      "x": 360,
+      "y": 70,
+      "width": 920,
+      "height": 470,
+      "type": "security"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "web",
+      "label": "Browser application",
+      "sublabel": "External entry",
+      "type": "browser",
+      "x": 70,
+      "y": 160,
+      "width": 200,
+      "height": 112
+    },
+    {
+      "id": "gateway",
+      "label": "Identity and request routing gateway",
+      "type": "gateway",
+      "x": 420,
+      "y": 150,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "service",
+      "label": "Order query and approval service",
+      "type": "backend",
+      "x": 760,
+      "y": 150,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "cache",
+      "label": "Short-lived query cache",
+      "type": "memory",
+      "x": 420,
+      "y": 370,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "db",
+      "label": "Order and approval database",
+      "type": "database",
+      "x": 760,
+      "y": 370,
+      "width": 220,
+      "height": 112,
+      "group": "private"
+    },
+    {
+      "id": "queue",
+      "label": "Async tasks and notification queue",
+      "type": "queue",
+      "x": 1060,
+      "y": 370,
+      "width": 180,
+      "height": 112,
+      "group": "private"
+    }
+  ],
+  "connections": [
+    {
+      "from": "web",
+      "to": "gateway",
+      "label": "Authentication request",
+      "flow": "control"
+    },
+    {
+      "from": "gateway",
+      "to": "service",
+      "label": "Validated request",
+      "flow": "control"
+    },
+    {
+      "from": "service",
+      "to": "gateway",
+      "label": "Query response",
+      "flow": "data"
+    },
+    {
+      "from": "service",
+      "to": "cache",
+      "label": "Read cache",
+      "flow": "read"
+    },
+    {
+      "from": "service",
+      "to": "db",
+      "label": "Query records",
+      "flow": "read"
+    },
+    {
+      "from": "service",
+      "to": "queue",
+      "label": "Submit notification task",
+      "flow": "async"
+    }
+  ]
+}

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

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Expected diagnostics"
+  },
+  "nodes": [
+    {
+      "id": "tiny",
+      "label": "A complete long label that cannot fit explicit size",
+      "x": -12,
+      "y": 40,
+      "width": 48,
+      "height": 24
+    },
+    {
+      "id": "overlap",
+      "label": "Overlap",
+      "x": 20,
+      "y": 44,
+      "width": 100,
+      "height": 60
+    }
+  ],
+  "connections": [
+    {
+      "from": "tiny",
+      "to": "overlap",
+      "waypoints": [
+        [
+          30,
+          50
+        ],
+        [
+          800,
+          -20
+        ]
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,53 @@
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": {
+    "title": "Order query and cache refill"
+  },
+  "participants": [
+    {
+      "id": "client",
+      "label": "Browser client",
+      "type": "frontend"
+    },
+    {
+      "id": "api",
+      "label": "Order service API",
+      "type": "backend"
+    },
+    {
+      "id": "db",
+      "label": "Persistent database",
+      "type": "database"
+    }
+  ],
+  "messages": [
+    {
+      "from": "client",
+      "to": "api",
+      "label": "Query order details and current payment status"
+    },
+    {
+      "from": "api",
+      "to": "api",
+      "label": "Validate identity and order access"
+    },
+    {
+      "from": "api",
+      "to": "db",
+      "label": "Cache miss: read order records"
+    },
+    {
+      "from": "db",
+      "to": "api",
+      "label": "Return order records and payment status",
+      "variant": "return"
+    },
+    {
+      "from": "api",
+      "to": "client",
+      "label": "Return results and update the page",
+      "variant": "return"
+    }
+  ]
+}

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

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

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/{fec-image-generation → cc-technical-diagrams}/references/diagram-workflows.md

@@ -7,10 +7,10 @@
 | 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 | HTML `architecture` IR, Mermaid flowchart, C4/Structurizr, SVG/HTML, draw.io | Layer grouping, trust boundaries, data flow direction, legends. |
+| 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 | HTML `workflow` IR, Mermaid flowchart, SVG, draw.io | Decision labels, terminal states, loop-back readability, connector spacing, exception path clarity. |
+| 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
@@ -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.
@@ -50,7 +50,7 @@ Coordinates are PNG pixel coordinates after export. Boxes should cover visible l
 ## 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, reduce label length, or increase export scale.
+- **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.
@@ -67,8 +67,15 @@ 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
 
 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/{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
@@ -226,7 +226,7 @@ node skills/fec-image-generation/scripts/png-qa.mjs \
 Repair the source JSON or rendering dimensions rather than editing pixels:
 
 - Overlap: split dense lanes or add rows/lanes/stages.
-- Truncated label: shorten labels, add `sublabel`, or widen nodes.
+- 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.
@@ -234,3 +234,10 @@ Repair the source JSON or rendering dimensions rather than editing pixels:
 ## 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.