@bovinphang/frontend-craft 2.8.0 → 3.0.0

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

package/localized/zh-CN/skills/fec-image-generation/scripts/png-qa.mjs

@@ -3,7 +3,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
+import { segmentHits } from "./diagram-layout.mjs";
+import { pathToFileURL } from "node:url";
 
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
 const args = parseArgs(process.argv.slice(2));
 
 if (!args.png || args.help) {
@@ -26,6 +29,8 @@ try {
   process.exit(1);
 }
 
+}
+
 function parseArgs(values) {
   const parsed = { format: "markdown", strict: false, help: false };
   for (let index = 0; index < values.length; index += 1) {
@@ -44,12 +49,13 @@ function parseArgs(values) {
 }
 
 function printHelp() {
-  console.log(`Usage: node skills/fec-image-generation/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
+  console.log(`Usage: node skills/cc-technical-diagrams/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
 }
 
 function readManifest(filePath) {
   const manifest = JSON.parse(fs.readFileSync(filePath, "utf8"));
   return {
+    ...manifest,
     canvas: manifest.canvas,
     boxes: Array.isArray(manifest.boxes) ? manifest.boxes : [],
     connectors: Array.isArray(manifest.connectors) ? manifest.connectors : [],
@@ -188,6 +194,8 @@ function analyze(image, manifest, strict) {
       inkCoverage: Number(ink.coverage.toFixed(6)),
       inkBounds: ink.bounds,
     },
+    measurement: manifest?.measurement ?? "image-only",
+    verification: { image: "checked", geometry: manifest ? "checked" : "unavailable", text: manifest?.measurement === "browser" ? "browser-measured" : "estimated-or-unavailable", visual: "pending" },
     issues,
     nextActions: [...nextActions],
   };
@@ -243,7 +251,7 @@ function colorDistance(left, right) {
   return Math.abs(left.r - right.r) + Math.abs(left.g - right.g) + Math.abs(left.b - right.b) + Math.abs(left.a - right.a);
 }
 
-function analyzeManifest(image, manifest, issues, nextActions, strict) {
+export function analyzeManifest(image, manifest, issues, nextActions, strict) {
   if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
     addIssue(
       issues,
@@ -254,12 +262,26 @@ function analyzeManifest(image, manifest, issues, nextActions, strict) {
     );
   }
 
-  const boxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  for (const box of manifest.boxes) if (![box.x,box.y,box.width,box.height].every(Number.isFinite) || box.width <= 0 || box.height <= 0) addIssue(issues,nextActions,"invalid-box-geometry",`Invalid geometry for "${box.id}".`,"Correct source dimensions.");
+  const allBoxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  const boxes = allBoxes.filter((box) => box.kind !== "group");
+  for (const issue of manifest.issues ?? []) addIssue(issues, nextActions, issue.code, issue.message, "Fix the source layout and render again.");
+  const labels = manifest.labels ?? [];
+  for (const label of labels) {
+    const owner = allBoxes.find((box) => box.id === label.owner);
+    if (label.kind === "node" && !owner) addIssue(issues,nextActions,"label-owner-missing",`Label "${label.id}" has an unknown node owner.`,"Correct label ownership in the manifest.");
+    if (![label.x,label.y,label.width,label.height].every(Number.isFinite) || label.width < 0 || label.height < 0) addIssue(issues,nextActions,"invalid-label-geometry",`Label "${label.id}" has invalid bounds.`,"Measure source labels again.");
+    if (label.x < 0 || label.y < 0 || label.x + label.width > image.width || label.y + label.height > image.height) addIssue(issues, nextActions, "label-out-of-bounds", `Label "${label.id}" exceeds the canvas.`, "Expand the canvas or adjust the source label position.");
+    if (label.kind === "node" && owner && (label.x < owner.x || label.y < owner.y || label.x + label.width > owner.x + owner.width || label.y + label.height > owner.y + owner.height)) addIssue(issues, nextActions, "node-text-overflow", `Label "${label.id}" exceeds node "${owner.id}".`, "Expand the source node or adjust its text layout.");
+    if (Array.isArray(label.lines) && label.lines.join("").replace(/\r?\n/g, "") !== String(label.text ?? "").replace(/\r?\n/g, "")) addIssue(issues, nextActions, "label-content-loss", `Label "${label.id}" does not preserve source text.`, "Restore the complete source label.");
+    if (label.kind === "edge") for (const box of boxes) if (overlapArea(label, box) > 0) addIssue(issues, nextActions, "edge-label-collision", `Label "${label.id}" overlaps node "${box.id}".`, "Move the edge label to a clear route segment.");
+  }
+  for (let i = 0; i < labels.length; i++) for (let j = i + 1; j < labels.length; j++) if (overlapArea(labels[i], labels[j]) > 0) addIssue(issues, nextActions, "text-overlap", `Labels "${labels[i].id}" and "${labels[j].id}" overlap.`, "Increase label spacing in the source.");
   for (const box of boxes) {
     if (box.x < 0 || box.y < 0 || box.x + box.width > image.width || box.y + box.height > image.height) {
       addIssue(issues, nextActions, "box-out-of-bounds", `Box "${box.id}" is outside the canvas.`, "Move out-of-bounds nodes inside the canvas or expand the canvas.");
     }
-    if (box.label && estimateLabelOverflow(box, strict)) {
+    if (!labels.length && box.label && estimateLabelOverflow(box, strict)) {
       addIssue(issues, nextActions, "label-overflow", `Box "${box.id}" label is likely to overflow.`, "Wrap or shorten labels, widen boxes, or increase export scale.");
     }
   }
@@ -277,9 +299,12 @@ function analyzeManifest(image, manifest, issues, nextActions, strict) {
   const segments = [];
   for (const connector of manifest.connectors) {
     const points = normalizePoints(connector.points);
+    if(points.some(point=>point.x<0||point.y<0||point.x>image.width||point.y>image.height)) addIssue(issues,nextActions,"connector-out-of-bounds",`Connector "${connector.id}" exceeds the canvas.`,"Correct explicit waypoints or expand the source canvas.");
+    if (points.length < 2 || points.every((point) => point.x === points[0].x && point.y === points[0].y)) addIssue(issues, nextActions, "degenerate-connector", `Connector "${connector.id ?? "unnamed"}" has no visible path.`, "Give self calls a loop and other connectors distinct endpoints.");
     for (let index = 0; index < points.length - 1; index += 1) {
       const segment = { connector, a: points[index], b: points[index + 1] };
       segments.push(segment);
+      for (const label of labels) if (segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],label)) addIssue(issues,nextActions,"connector-through-text",`Connector "${connector.id}" crosses label "${label.id}".`,"Move the source label or route around its text.");
       for (const box of boxes) {
         if (box.id === connector.from || box.id === connector.to) continue;
         if (segmentIntersectsBox(segment, box)) {
@@ -306,6 +331,7 @@ function normalizeBox(box) {
   if (!box || typeof box.id !== "string") return null;
   const normalized = {
     id: box.id,
+    kind: box.kind,
     x: Number(box.x),
     y: Number(box.y),
     width: Number(box.width),
@@ -347,6 +373,10 @@ function overlapArea(left, right) {
 }
 
 function segmentIntersectsBox(segment, box) {
+  return segmentHits([segment.a.x,segment.a.y],[segment.b.x,segment.b.y],box);
+}
+
+function legacySegmentIntersectsBox(segment, box) {
   if (pointInsideBox(segment.a, box) || pointInsideBox(segment.b, box)) return true;
   const edges = [
     [{ x: box.x, y: box.y }, { x: box.x + box.width, y: box.y }],
@@ -399,7 +429,8 @@ function rangesOverlap(left, right) {
 
 function addIssue(issues, nextActions, code, message, action) {
   issues.push({ code, message, action });
-  nextActions.add(action);
+  if (typeof nextActions.add === "function") nextActions.add(action);
+  else if (!nextActions.includes(action)) nextActions.push(action);
 }
 
 function renderMarkdown(report) {

package/localized/zh-CN/skills/fec-react-project-standard/SKILL.md

@@ -89,3 +89,9 @@ description: 用于设计或审查 React + TypeScript 项目结构、feature/mod
 - 对新增模块，优先输出最小可落地结构，而不是一次性过度设计
 - 对重构任务，优先保证可迁移性和风险可控
 - 对性能相关 React 变更，说明触发的风险类别、证据来源和验证命令
+
+泛型组件的 Props 与回调契约见[组件类型示例](references/generic-component-types.md)。
+
+## 工程实践
+
+按当前任务读取[本入口工程细则](references/engineering-practices.md)，再按链接选择公共原则。规则级别与例外以实际项目契约为准；不因产品前后端标签限制语言或职责。

package/localized/zh-CN/skills/fec-react-project-standard/examples/engineering/README.md

@@ -0,0 +1,7 @@
+# React 异步状态所有权 — EP-UI-01
+
+本例用 Testing Library 和 JSDOM 渲染真实 React 组件。手动控制 A/B 完成顺序，验证晚到的 A 不覆盖 B；卸载时验证本组件拥有的 signal 已取消。不依赖定时器或真实网络排序。设置 `CRAFT_ENGINEERING_DEFECTIVE=1` 会移除两种保护并触发断言失败；默认实现具备保护。
+
+在本目录显式执行 `pnpm install --frozen-lockfile` 后运行 `pnpm test`。将缺陷环境变量设为 `1` 观察反例，设为 `0` 验证修复。仓库维护时在产品根目录执行 `pnpm run verify:engineering -- --prepare`，得到隔离准备环境与配对日志；后续复验不带 `--prepare`。常规仓库测试不会安装样例依赖，源文件与缓存分离。
+
+精确依赖和锁仅属于本例。Node >=22.18、React/DOM 19.3.1、Testing Library React 16.3.3/DOM 10.4.2 和 JSDOM 29.1.1 是兼容的样例目标，不要求项目升级。JSDOM 31 要求比本机更高的 Node 24 小版本。本例的真实 DOM 状态断言不证明浏览器渲染、Vue watcher、共享查询缓存、后端回滚、桌面界面、签名或生产网络集成。取消请求不能撤销远端已提交的写入。参见[本入口决策](../../references/engineering-practices.md)。

package/localized/zh-CN/skills/fec-react-project-standard/examples/engineering/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "craft-react-request-example",
+  "private": true,
+  "type": "module",
+  "engines": {"node": ">=22.18.0"},
+  "packageManager": "pnpm@12.4.1",
+  "scripts": {"test": "node --test --test-reporter=tap request-view.test.mjs"},
+  "dependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/dom": "10.4.2",
+    "jsdom": "29.1.1"
+  }
+}