@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/skills/fec-drawio-studio/references/diagram-patterns.md

@@ -6,8 +6,10 @@ Use these conventions when a user asks for a named technical diagram.
 
 - Group nodes by tier: client, edge, service, data, external.
 - Use swimlanes or grouped containers when boundaries matter.
+- For layered block architecture, prefer horizontal tiers with left-side tier labels, content-driven containers, and optional cross-cutting sidebars for security, monitoring or governance.
 - Put bus or event-stream nodes near the center of publisher/subscriber rows.
 - Use cylinders for databases, rounded rectangles for services, dashed outlines for external systems.
+- Use arrows only when data flow or dependency direction matters; use spatial grouping for pure capability stacks.
 
 ## ERD
 
@@ -15,18 +17,21 @@ Use these conventions when a user asks for a named technical diagram.
 - Mark primary keys and foreign keys in labels.
 - Use dashed relationship edges when cardinality is not fully known.
 - Prefer top-to-bottom layout for schemas with multiple relation clusters.
+- Use stable table widths and row heights so long column names wrap instead of resizing neighboring tables.
 
 ## UML Class
 
 - Use a class box split into name, fields and methods.
 - Use hollow triangle arrows for inheritance, dashed hollow triangle for interface implementation.
 - Keep interfaces or abstract bases above concrete classes.
+- Keep associations orthogonal and label multiplicity near the edge segment it describes.
 
 ## Sequence
 
 - Lay participants left-to-right and time top-to-bottom.
 - Keep request, response and async message styles visually distinct.
 - Add activation boxes only when they clarify nested work.
+- Leave enough horizontal spacing for message labels; if labels collide, wrap text or split the interaction into phases.
 
 ## ML / Deep Learning
 
@@ -39,3 +44,17 @@ Use these conventions when a user asks for a named technical diagram.
 - Use ovals for start/end, rectangles for process, diamonds for decisions.
 - Label decision branches.
 - Merge branches back to a central path when possible.
+- Keep the primary path vertical. Route alternate or error branches sideways and back to the main path with orthogonal edges.
+- For editable draw.io flowcharts, follow [flowchart-quality.md](flowchart-quality.md) before final delivery.
+
+## Mindmap
+
+- Put the central concept in the middle and distribute first-level branches across quadrants.
+- Use curved edges without arrowheads and keep each branch color consistent from parent to leaves.
+- Fan leaves away from the center; do not let branches cross through the central label.
+
+## Network Topology
+
+- Use hierarchical rows such as internet, edge, switching/routing and devices.
+- Distinguish wired and wireless links visually, usually solid for wired and dashed for wireless.
+- Keep endpoint devices aligned in rows or columns so connection paths remain scannable.

package/skills/fec-drawio-studio/references/flowchart-quality.md

@@ -0,0 +1,49 @@
+# Flowchart Quality
+
+Use this reference when a draw.io / diagrams.net deliverable is a process, workflow, approval path, release path, incident response path, onboarding flow or other flowchart that must remain readable after opening in diagrams.net.
+
+## Readability Contract
+
+- Keep manually authored flowcharts narrow. Prefer `pageWidth` between 600 and 800; do not exceed 800 unless the diagram is intentionally a wide cross-functional table.
+- Set `dx` and `dy` close to the page dimensions so diagrams.net does not initially zoom the drawing until labels become tiny.
+- Put the primary path top-to-bottom. Use side branches only for alternatives, failures, retries and exceptions, then return them to the main path with orthogonal connectors.
+- Split more than five dense stages into multiple diagrams or pages instead of making one oversized canvas.
+
+## Stage Grouping
+
+- Use `swimlane` containers for real stages, actors, phases or bounded groups; avoid loose rectangles when a title and containment relationship matter.
+- Keep stage containers on a 10px grid, normally with a 20px outer page margin and 30-40px vertical breathing room between stages.
+- Give container headers a readable hierarchy: stage labels around 14-16px, bold, with a clear border color.
+- Set stage containers to `connectable="0"` and `collapsible=0` so connectors target intentional nodes and the diagram does not gain collapse controls.
+- Size containers to fit their children with 15px or more bottom padding. A container with large one-sided blank space usually needs a layout pass.
+
+## Labels
+
+- Keep node text centered for process boxes unless a table-like artifact genuinely needs aligned rows.
+- Use `whiteSpace=wrap;html=1` on process nodes, and keep normal body text at 12px or larger.
+- Put the node title first, visually stronger than the body. Use concise labels and move long implementation detail into notes or metadata.
+- Use the same language as the user's request, and escape XML attribute content before saving.
+
+## Connectors
+
+- Use `edgeStyle=orthogonalEdgeStyle` for normal flowchart connectors.
+- Make the main stage-to-stage path visually stronger than secondary edges, for example with a thicker stroke and a consistent accent color.
+- Label decision branches and exception paths close to the edge segment they describe.
+- For fan-out from one node to several peers, use explicit `entryX`, `entryY`, `exitX` and `exitY` anchors so branches do not cross.
+- Route retry, rollback and loop connectors around the left or right margin with explicit waypoints instead of diagonal shortcuts through content.
+
+## Visual System
+
+- Use a small palette with one color per stage type or actor group. Keep process node fills neutral and let borders or headers carry the stage color.
+- Reserve warning, failure, pending and future states for exceptional nodes; do not use status colors as decoration.
+- Keep container corners square when the stage boundary is structural; rounded corners are fine for ordinary process nodes.
+
+## Final Review
+
+Before delivery, run:
+
+```bash
+node skills/fec-drawio-studio/scripts/diagram-lint.mjs diagram.drawio --format markdown --strict
+```
+
+Then manually check that the opened diagram has no crossed main-path connectors, no clipped labels, no collapsed-looking stages, and no unreadably small text at the default diagrams.net zoom.

package/skills/fec-drawio-studio/references/layout-and-export.md

@@ -2,7 +2,7 @@
 
 ## Auto Layout
 
-Use `layout-graph.mjs` for dependency graphs, code structure maps and diagrams with more than about 15 nodes.
+Use `layout-graph.mjs` for dependency graphs, code structure maps and diagrams with more than about 15 nodes. For smaller diagrams, manual XML is acceptable when the coordinates, containers and edge anchors can be reviewed directly.
 
 ```bash
 node skills/fec-drawio-studio/scripts/layout-graph.mjs graph.json --output diagram.drawio --manifest layout.json
@@ -25,21 +25,36 @@ Input graph:
 
 Graphviz `dot` is optional. If it is missing, hand-place the diagram or deliver XML plus a diagrams.net URL.
 
+## Manual Layout
+
+- Align visible vertex `x` and `y` values to the 10px grid.
+- Keep at least 60px outer page margin and enough space that connectors do not cross labels.
+- Use equal sizes and equal gaps for sibling nodes in the same row or column unless content requires a different size.
+- Encode explicit label breaks as `
`; do not put literal `\n` in draw.io `value` attributes.
+- Include `whiteSpace=wrap;html=1` on labels and use `fontSize=14` by default, with 12 as the smallest readable exception.
+- Size containers, sidebars and swimlanes to their content plus balanced padding. If a final row is incomplete, center it or split the group instead of leaving a large empty tail.
+
 ## Export
 
 Preview:
 
 ```bash
-drawio -x -f png --width 2000 -o diagram.png diagram.drawio
+node skills/fec-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --width 2000
 ```
 
 Final editable PNG:
 
 ```bash
-drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio
+node skills/fec-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.drawio.png --scale 2 --embed
 node skills/fec-drawio-studio/scripts/png-embed-fix.mjs diagram.drawio.png
 ```
 
+Preview export can be checked without draw.io side effects:
+
+```bash
+node skills/fec-drawio-studio/scripts/drawio-export.mjs diagram.drawio --format png --output diagram.png --scale 2 --width 2000 --dry-run --json
+```
+
 Fallback URL:
 
 ```bash

package/skills/fec-drawio-studio/references/xml-and-mermaid.md

@@ -16,6 +16,9 @@ Use this reference to choose the lightest editable diagram source that still mee
 - Put child nodes inside their visual container by setting `parent` to the container id and using coordinates relative to that container.
 - Put edges that cross container boundaries at `parent="1"` so they are not clipped by a lane or group.
 - Every edge must contain `<mxGeometry relative="1" as="geometry"/>`; do not use self-closing edge cells.
+- Use `&#xa;` for forced line breaks in `value` attributes. Literal `\n` renders as text in draw.io and should be treated as a quality issue.
+- Keep manually placed vertices on a 10px grid, within `pageWidth` / `pageHeight`, and with stable dimensions so hover, labels and exports do not shift the layout.
+- For manually authored flowcharts, keep `pageWidth` at or below 800 unless the diagram is deliberately a wide matrix or cross-functional table.
 
 ## Containers And Process Layout
 
@@ -35,6 +38,7 @@ Use this reference to choose the lightest editable diagram source that still mee
 
 - Match diagram label language to the user's language.
 - Add `html=1` whenever labels contain HTML markup or escaped `<br>` formatting.
+- Include `whiteSpace=wrap;html=1` on normal shape labels so long text wraps consistently.
 - Escape XML attribute values: `&`, `<`, `>`, and `"` must be entities.
 - Prefer adaptive colors and simple palettes; specify dark-mode overrides only when automatic inversion makes labels or shapes unclear.
 
@@ -51,4 +55,4 @@ Use this reference to choose the lightest editable diagram source that still mee
 - Do not leave raw ampersands or angle brackets inside attribute values.
 - Do not use duplicate ids.
 - Do not leave edges pointing to missing source or target cells.
-- Run `diagram-lint.mjs` before final handoff.
+- Run `diagram-lint.mjs` before final handoff. Use `--strict` when the exported artifact is a final deliverable so warnings such as overlaps, literal line breaks, missing wrapping styles, tiny fonts, grid drift and page overflow block the handoff.

package/skills/fec-drawio-studio/scripts/diagram-lint.mjs

@@ -8,6 +8,18 @@ export function lintDrawio(xml) {
   if (!/<mx(Cell|file|GraphModel)\b/.test(xml)) warnings.push("No draw.io graph markers found");
   if (/<mxCell\b[^>]*\bedge="1"[^>]*\/>/.test(xml)) errors.push("edge mxCell must not be self-closing; add mxGeometry relative=\"1\"");
 
+  const graphModel = attrsOf(xml.match(/<mxGraphModel\b([^>]*)>/)?.[1] ?? "");
+  const pageWidth = Number(graphModel.pageWidth);
+  const pageHeight = Number(graphModel.pageHeight);
+  const viewportWidth = Number(graphModel.dx);
+  const viewportHeight = Number(graphModel.dy);
+  if (Number.isFinite(pageWidth) && pageWidth > 800) warnings.push(`pageWidth ${pageWidth} is above the readable manual-flowchart maximum of 800`);
+  if (Number.isFinite(pageWidth) && Number.isFinite(viewportWidth) && viewportWidth < pageWidth * 0.75) {
+    warnings.push(`dx ${viewportWidth} is much smaller than pageWidth ${pageWidth}; diagrams.net may initially zoom labels too small`);
+  }
+  if (Number.isFinite(pageHeight) && Number.isFinite(viewportHeight) && viewportHeight < pageHeight * 0.5) {
+    warnings.push(`dy ${viewportHeight} is much smaller than pageHeight ${pageHeight}; diagrams.net may initially zoom labels too small`);
+  }
   const cellRe = /<mxCell\b([^>]*?)(?:\/>|>([\s\S]*?)<\/mxCell>)/g;
   const objectByCellIndex = objectsByCellIndex(xml);
   const cells = [];
@@ -28,6 +40,7 @@ export function lintDrawio(xml) {
     for (const [name, value] of rawAttrsOf(match[1])) {
       if (hasUnescapedAmpersand(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped ampersand`);
       if (/[<>]/.test(value)) errors.push(`cell ${id} attribute ${name} contains an unescaped angle bracket`);
+      if (name === "value" && /\\n/.test(value)) warnings.push(`cell ${id} value contains literal \\n; use &#xa; for draw.io line breaks`);
     }
     const geom = body.match(/<mxGeometry\b([^>]*?)(?:\/>|>)/)?.[1];
     cells.push({ id, attrs, body, geom: geom ? attrsOf(geom) : null });
@@ -49,14 +62,33 @@ export function lintDrawio(xml) {
     }
     if (attrs.edge === "1" && !geom) errors.push(`edge ${id} is missing mxGeometry`);
     if (attrs.edge === "1" && (!attrs.source || !attrs.target)) warnings.push(`edge ${id} has no source or target`);
+    if (attrs.edge === "1" && attrs.style && !styleHas(attrs.style, "edgeStyle", "orthogonalEdgeStyle")) {
+      warnings.push(`edge ${id} should use orthogonalEdgeStyle for readable technical diagram routing`);
+    }
     if (attrs.vertex === "1") {
       if (looksLikeHtml(attrs.value) && !styleHas(attrs.style, "html", "1")) warnings.push(`cell ${id} label contains HTML but style does not include html=1`);
+      if (!styleHas(attrs.style, "whiteSpace", "wrap")) warnings.push(`cell ${id} style should include whiteSpace=wrap for label wrapping`);
+      if (!styleHas(attrs.style, "html", "1")) warnings.push(`cell ${id} style should include html=1 for predictable label rendering`);
+      const fontSize = styleNumber(attrs.style, "fontSize");
+      if (Number.isFinite(fontSize) && fontSize < 12) warnings.push(`cell ${id} fontSize ${fontSize} is below the readable minimum of 12`);
+      if (isSwimlane(attrs.style)) {
+        if (attrs.connectable !== "0") warnings.push(`swimlane ${id} should set connectable="0" so connectors target intentional nodes`);
+        if (styleValue(attrs.style, "collapsible") !== "0") warnings.push(`swimlane ${id} should set collapsible=0 to avoid collapse controls in deliverables`);
+        if (styleValue(attrs.style, "rounded") !== "0") warnings.push(`swimlane ${id} should use rounded=0 for clear structural stage boundaries`);
+        if (Number.isFinite(fontSize) && fontSize < 14) warnings.push(`swimlane ${id} title fontSize ${fontSize} is below the recommended flowchart stage range of 14-16`);
+      } else if (isLikelyProcessNode(attrs.style)) {
+        const align = styleValue(attrs.style, "align");
+        if (align && align !== "center") warnings.push(`process node ${id} should use align=center for flowchart readability`);
+      }
       if (!geom) errors.push(`vertex ${id} is missing mxGeometry`);
       else {
         const rect = rectOf(geom);
         if (!Number.isFinite(rect.w) || !Number.isFinite(rect.h)) errors.push(`vertex ${id} has invalid size`);
         else if (rect.w <= 0 || rect.h <= 0) warnings.push(`vertex ${id} has non-positive size`);
         if (rect.x < 0 || rect.y < 0) warnings.push(`vertex ${id} has negative position`);
+        if (!onGrid(rect.x) || !onGrid(rect.y)) warnings.push(`vertex ${id} position should align to the 10px grid`);
+        if (Number.isFinite(pageWidth) && rect.x + rect.w > pageWidth) warnings.push(`vertex ${id} extends beyond pageWidth ${pageWidth}`);
+        if (Number.isFinite(pageHeight) && rect.y + rect.h > pageHeight) warnings.push(`vertex ${id} extends beyond pageHeight ${pageHeight}`);
       }
     }
   }
@@ -119,6 +151,32 @@ function styleHas(style = "", key, expected) {
   });
 }
 
+function styleNumber(style = "", key) {
+  for (const part of style.split(";")) {
+    const [partKey, value] = part.split("=", 2);
+    if (partKey === key) return Number(value);
+  }
+  return NaN;
+}
+
+function styleValue(style = "", key) {
+  for (const part of style.split(";")) {
+    const [partKey, value] = part.split("=", 2);
+    if (partKey === key) return value ?? "";
+  }
+  return undefined;
+}
+
+function isSwimlane(style = "") {
+  return style.split(";").some((part) => part === "swimlane" || part === "shape=swimlane");
+}
+
+function isLikelyProcessNode(style = "") {
+  const shape = styleValue(style, "shape");
+  if (shape) return ["process", "rectangle", "rhombus", "terminator"].includes(shape);
+  return style.includes("rounded=1") || style.includes("whiteSpace=wrap");
+}
+
 function rectOf(geom) {
   return {
     x: Number(geom.x ?? 0),
@@ -128,6 +186,10 @@ function rectOf(geom) {
   };
 }
 
+function onGrid(value, grid = 10) {
+  return Number.isFinite(value) && Math.abs(value / grid - Math.round(value / grid)) < 1e-9;
+}
+
 function overlaps(a, b) {
   return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
 }

package/skills/fec-drawio-studio/scripts/drawio-export.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { formatResult, parseArgs } from "./studio-core.mjs";
+
+const INSTALL_HINTS = [
+  "draw.io desktop CLI was not found.",
+  "Install draw.io desktop, then rerun the export.",
+  "Windows: winget install JGraph.Draw",
+  "macOS: brew install --cask drawio",
+  "Linux: install drawio from your package manager or snap install drawio",
+  "Manual download: https://github.com/jgraph/drawio-desktop/releases",
+];
+
+export function buildExportPlan(input, args = {}, env = process.env, platform = process.platform) {
+  const drawio = findDrawio(args.drawio, env, platform);
+  if (!drawio) {
+    return {
+      ok: false,
+      title: "Draw.io Export",
+      errors: [INSTALL_HINTS.join("\n")],
+      command: null,
+    };
+  }
+
+  const format = String(args.format ?? "png");
+  const output = String(args.output ?? defaultOutput(input, format));
+  const commandArgs = ["-x", "-f", format];
+  if (args.embed) commandArgs.push("-e");
+  if (args.scale) commandArgs.push("-s", String(args.scale));
+  if (args.width) commandArgs.push("--width", String(args.width));
+  if (args.border) commandArgs.push("--border", String(args.border));
+  if (args.crop) commandArgs.push("--crop");
+  if (args.page !== undefined) commandArgs.push("-p", String(args.page));
+  commandArgs.push("-o", output, input);
+
+  return {
+    ok: true,
+    title: "Draw.io Export",
+    drawio,
+    command: [drawio, ...commandArgs],
+    output,
+    format,
+    dryRun: Boolean(args.dryRun),
+    errors: [],
+  };
+}
+
+export function findDrawio(explicitPath, env = process.env, platform = process.platform) {
+  if (explicitPath) return existingFile(explicitPath);
+
+  for (const command of ["drawio", "draw.io"]) {
+    const found = findOnPath(command, env, platform);
+    if (found) return found;
+  }
+
+  for (const candidate of defaultCandidates(env, platform)) {
+    const found = existingFile(candidate);
+    if (found) return found;
+  }
+
+  return null;
+}
+
+function findOnPath(command, env, platform) {
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const dirs = pathValue.split(path.delimiter).filter(Boolean);
+  const extensions = platform === "win32" ? pathExtensions(env) : [""];
+  for (const dir of dirs) {
+    for (const ext of extensions) {
+      const candidate = path.join(dir, command.endsWith(ext) ? command : `${command}${ext}`);
+      const found = existingFile(candidate);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function pathExtensions(env) {
+  const configured = env.PATHEXT ? env.PATHEXT.split(";").filter(Boolean) : [".EXE", ".CMD", ".BAT", ""];
+  return [...new Set(["", ...configured, ...configured.map((item) => item.toLowerCase())])];
+}
+
+function defaultCandidates(env, platform) {
+  if (platform === "win32") {
+    return [
+      path.join(env.ProgramFiles ?? "C:\\Program Files", "draw.io", "draw.io.exe"),
+      path.join(env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)", "draw.io", "draw.io.exe"),
+      path.join(env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), "Programs", "draw.io", "draw.io.exe"),
+    ];
+  }
+  if (platform === "darwin") {
+    return ["/Applications/draw.io.app/Contents/MacOS/draw.io"];
+  }
+  return ["/usr/bin/drawio", "/usr/local/bin/drawio", "/snap/bin/drawio"];
+}
+
+function existingFile(candidate) {
+  if (!candidate) return null;
+  const resolved = path.resolve(candidate);
+  return fs.existsSync(resolved) && fs.statSync(resolved).isFile() ? resolved : null;
+}
+
+function defaultOutput(input, format) {
+  return `${input.replace(/\.(drawio|xml)$/i, "")}.${format}`;
+}
+
+function printFailure(plan, args) {
+  const output = formatResult(plan, args.formatOutput ?? (args.json ? "json" : "markdown"));
+  process.stderr.write(output);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const input = args._[0];
+if (!input) {
+  console.error("usage: node drawio-export.mjs <file.drawio> [--format png|svg|pdf] [--output file] [--scale 2] [--width 2000] [--border 20] [--dry-run] [--json]");
+  process.exit(2);
+}
+
+const plan = buildExportPlan(input, args);
+if (!plan.ok) {
+  printFailure(plan, args);
+  process.exit(1);
+}
+
+if (args.dryRun) {
+  process.stdout.write(formatResult(plan, args.formatOutput ?? (args.json ? "json" : "markdown")));
+  process.exit(0);
+}
+
+const result = spawnSync(plan.command[0], plan.command.slice(1), { stdio: "inherit" });
+process.exit(result.status ?? 1);

package/skills/fec-drawio-studio/scripts/shape-query.mjs

@@ -1,28 +1,44 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
-import zlib from "node:zlib";
 import { formatResult, parseArgs, skillDir } from "./studio-core.mjs";
 
-const INDEX = path.join(skillDir, "data", "shape-index.json.gz");
+const INDEX = path.join(skillDir, "data", "shape-index.json");
 const ALIASES = new Map([
-  ["亚马逊", "aws"], ["阿里云", "alibaba cloud"], ["微软云", "azure"], ["谷歌云", "gcp"],
-  ["云", "cloud"], ["数据库", "database"], ["队列", "queue"], ["网关", "gateway"],
-  ["服务", "service"], ["用户", "user"], ["角色", "actor"], ["流程", "flowchart"],
-  ["容器", "container"], ["网络", "network"], ["交换机", "switch"], ["路由器", "router"],
-  ["函数", "lambda"], ["对象存储", "storage"], ["消息", "message"],
+  ["亚马逊", "aws"],
+  ["阿里云", "alibaba cloud"],
+  ["微软云", "azure"],
+  ["谷歌云", "gcp"],
+  ["云", "cloud"],
+  ["数据库", "database"],
+  ["队列", "queue"],
+  ["网关", "gateway"],
+  ["服务", "service"],
+  ["用户", "user"],
+  ["角色", "actor"],
+  ["流程", "flowchart"],
+  ["容器", "container"],
+  ["网络", "network"],
+  ["交换机", "switch"],
+  ["路由器", "router"],
+  ["函数", "lambda"],
+  ["对象存储", "storage"],
+  ["消息", "message"],
 ]);
 
 export function loadShapes() {
-  return JSON.parse(zlib.gunzipSync(fs.readFileSync(INDEX)).toString("utf8"));
+  return JSON.parse(fs.readFileSync(INDEX).toString("utf8"));
 }
 
 export function queryShapes(shapes, query, options = {}) {
   const terms = expandTerms(query);
-  const category = options.category ? String(options.category).toLowerCase() : "";
+  const category = options.category
+    ? String(options.category).toLowerCase()
+    : "";
   const scored = [];
   for (const [index, shape] of shapes.entries()) {
-    const haystack = `${shape.title ?? ""} ${shape.tags ?? ""} ${shape.style ?? ""}`.toLowerCase();
+    const haystack =
+      `${shape.title ?? ""} ${shape.tags ?? ""} ${shape.style ?? ""}`.toLowerCase();
     if (category && !haystack.includes(category)) continue;
     let score = 0;
     const title = String(shape.title ?? "").toLowerCase();
@@ -34,12 +50,30 @@ export function queryShapes(shapes, query, options = {}) {
       else if (tags.includes(term)) score += 12;
       if (fuzzyContains(haystack, term)) score += 4;
     }
-    if (score > 0) scored.push({ index, score, titleHits: terms.filter((term) => title.includes(term)).length, shape });
+    if (score > 0)
+      scored.push({
+        index,
+        score,
+        titleHits: terms.filter((term) => title.includes(term)).length,
+        shape,
+      });
   }
   return scored
-    .sort((a, b) => b.score - a.score || b.titleHits - a.titleHits || String(a.shape.title).localeCompare(String(b.shape.title)) || a.index - b.index)
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        b.titleHits - a.titleHits ||
+        String(a.shape.title).localeCompare(String(b.shape.title)) ||
+        a.index - b.index,
+    )
     .slice(0, Number(options.limit ?? 10))
-    .map(({ shape, score }) => ({ title: shape.title, w: shape.w, h: shape.h, style: shape.style, score }));
+    .map(({ shape, score }) => ({
+      title: shape.title,
+      w: shape.w,
+      h: shape.h,
+      style: shape.style,
+      score,
+    }));
 }
 
 function expandTerms(query) {
@@ -50,7 +84,11 @@ function expandTerms(query) {
     expanded.push(ALIASES.get(term) ?? term);
     if (term.includes("-")) expanded.push(...term.split("-"));
   }
-  return [...new Set(expanded.join(" ").match(/[a-z0-9._-]+|[\u4e00-\u9fff]+/g) ?? [])].filter((term) => term.length >= 2);
+  return [
+    ...new Set(
+      expanded.join(" ").match(/[a-z0-9._-]+|[\u4e00-\u9fff]+/g) ?? [],
+    ),
+  ].filter((term) => term.length >= 2);
 }
 
 function fuzzyContains(text, term) {
@@ -66,7 +104,9 @@ function fuzzyContains(text, term) {
 const args = parseArgs(process.argv.slice(2));
 const query = args._.join(" ");
 if (!query) {
-  console.error("usage: node shape-query.mjs <keywords> [--limit 10] [--category aws] [--format markdown|json]");
+  console.error(
+    "usage: node shape-query.mjs <keywords> [--limit 10] [--category aws] [--format markdown|json]",
+  );
   process.exit(2);
 }
 const results = queryShapes(loadShapes(), query, args);

package/skills/fec-e2e-testing/SKILL.md

@@ -1,42 +1,42 @@
 ---
 name: fec-e2e-testing
-description: Use when creating, maintaining, debugging, or reviewing real-browser end-to-end tests with Playwright or Cypress, including Page Object models, CI artifacts, traces, flaky tests, cross-page visual regression, and critical user journeys such as login, payment, permissions, or CRUD. For layer planning or tests close to UI components, choose the matching testing workflow first; Chinese triggers include E2E, 端到端测试, Playwright, Cypress.
+description: Use when creating, maintaining, debugging, or reviewing real-browser end-to-end tests with Playwright or Cypress, including Page Object models, CI artifacts, traces, flaky tests, cross-page visual regression, and critical user journeys such as login, payment, permissions, or CRUD. For layer planning or tests close to UI components, choose the matching testing workflow first; Chinese triggers include E2E, end-to-end testing, Playwright, Cypress.
 ---
 
-# E2E 测试规范
+# E2E Test Specification
 
 ## Purpose
 
-用真实浏览器验证关键用户旅程，发现单元测试无法覆盖的集成风险。
+Validate key user journeys with real browsers and uncover integration risks not covered by unit tests.
 
 ## Procedure
 
-1. 明确关键旅程：登录、购买、创建、搜索、权限、支付等跨页面流程优先；若只是选择测试层级，先做测试分层规划。
-2. 新项目优先 Playwright；已有 Cypress 项目沿用 Cypress，不为迁移而迁移。
-3. 用 Page Object 或 fixtures 封装登录、页面定位器和共享数据，spec 中避免裸选择器。
-4. 断言用户可见结果，依赖 Locator 自动等待、网络响应或可见状态，不使用固定 sleep。
-5. CI 必须上传 HTML report、截图、trace 或视频；flaky 用例要隔离、复现、标注来源并关联 issue。
-6. 调试失败时先读 trace、console、network 和截图，再改测试；不要把真实产品缺陷误判成 flaky。
-7. 对关键浏览器能力、支付、权限、上传和实时通信流程，记录测试环境、种子数据和清理策略。
-8. 测试数据必须可重复：优先使用 API seed、数据库 fixture、测试账号或 mock 服务；随机数据需带唯一前缀并在 teardown 清理。
+1. Clarify the key journeys: cross-page processes such as login, purchase, creation, search, permissions, payment, etc. are given priority; if you only choose the test level, do the test hierarchical planning first.
+2. New projects will be given priority by Playwright; existing Cypress projects will continue to use Cypress and will not be migrated for the sake of migration.
+3. Use Page Object or fixtures to encapsulate login, page locator and shared data, and avoid naked selectors in the spec.
+4. Assert that the user can see the results, relying on Locator automatic waiting, network response or visible status, without using fixed sleep.
+5. CI must upload HTML report, screenshots, trace or video; Flaky use cases must be isolated, reproduced, marked with sources and associated with issues.
+6. When debugging fails, read the trace, console, network and screenshots first, and then change the test; do not misjudge real product defects as flaky.
+7. Record the test environment, seed data and cleanup strategies for key browser capabilities, payment, permissions, uploads and real-time communication processes.
+8. Test data must be repeatable: API seeds, database fixtures, test accounts or mock services are preferred; random data must have a unique prefix and be cleaned in teardown.
 
-## 详细参考
+## Detailed reference
 
-- 需要目录结构、Page Object、spec 组织、配置、flaky 调试和产物示例时，加载 [references/playwright-patterns.md](references/playwright-patterns.md)。
-- 需要 CI 示例和 Markdown 报告模板时，加载 [references/e2e-ci-reporting.md](references/e2e-ci-reporting.md)。
-- 需要 Web3/钱包流程或高风险金融流程时，加载 [references/e2e-special-scenarios.md](references/e2e-special-scenarios.md)。
-- 需要跨页面截图或视觉回归配置时，加载 [references/e2e-visual-regression.md](references/e2e-visual-regression.md)。
+- Load [references/playwright-patterns.md](references/playwright-patterns.md) when you need directory structure, Page Object, spec organization, configuration, flaky debugging and production examples.
+- Load [references/e2e-ci-reporting.md](references/e2e-ci-reporting.md) when you need CI examples and Markdown report templates.
+- Load [references/e2e-special-scenarios.md](references/e2e-special-scenarios.md) when Web3/wallet flows or high-risk financial flows are required.
+- When cross-page screenshots or visual regression configuration are required, load [references/e2e-visual-regression.md](references/e2e-visual-regression.md).
 
 ## Constraints
 
-- 禁止依赖 `sleep` / 固定 `setTimeout` 作为主要同步手段。
-- 不在生产环境跑真实 E2E。
-- 避免在 E2E 中断言组件内部像素级样式；跨页面截图/视觉回归仅覆盖用户旅程中的关键页面状态。
-- 失败必须能靠截图、trace 或视频定位。
-- 组件内部契约测试分流到组件测试 workflow。
-- 不把不稳定等待、随机数据或依赖测试顺序带入 CI。
-- 不把重试次数当作 flaky 治理；重试只能保留证据，根因仍需定位。
+- Disable reliance on `sleep` / fixed `setTimeout` as primary synchronization means.
+- Do not run real E2E in production environment.
+- Avoid asserting component internal pixel-level styles in E2E; cross-page screenshots/visual regressions only cover key page states in the user journey.
+- Failure must be able to be located by taking screenshots, traces or videos.
+- Component internal contract testing is offloaded to component testing workflow.
+- Do not bring unstable waits, random data, or dependent test order into CI.
+- Do not treat the number of retries as flaky management; retries can only retain evidence, and the root cause still needs to be located.
 
 ## Expected Output
 
-关键用户旅程有稳定 E2E 覆盖，失败产物可定位问题，CI 中报告和 trace 可下载；flaky 用例有复现命令、隔离策略和后续 issue。
+Key user journeys have stable E2E coverage, failed products can locate problems, and reports and traces in CI can be downloaded; flaky use cases include recurrence commands, isolation strategies, and follow-up issues.