@nick848/fet 1.1.10 → 1.1.11

package/dist/cli/index.js

@@ -2090,6 +2090,12 @@ function renderFetConfig(scan, language = "zh-CN") {
         mode: "require_before_apply",
         whenNoTestScript: "block"
       },
+      visual: {
+        enabled: true,
+        compareMode: "layout-only",
+        requireBeforeVerify: "when_figma",
+        whenNoCapture: "warn"
+      },
       specLanguage: {
         style: "layered_bilingual",
         canonical: "en",
@@ -2274,7 +2280,7 @@ function tddResultsRelativePath(changeId) {
 
 // src/templates/tdd.ts
 function renderTddInstructions(changeId, manifest, language) {
-  const manifestPath2 = tddManifestRelativePath(changeId);
+  const manifestPath3 = tddManifestRelativePath(changeId);
   const specPath = tddSpecRelativePath(changeId);
   const caseList = manifest.cases.map((item) => `- \`${item.id}\`: ${item.title} \u2192 \`${item.testFile}\` (${item.testIds.join(", ")})`).join("\n");
   if (language === "en") {
@@ -2293,13 +2299,13 @@ Create or update unit tests **before** marking implementation tasks done in \`ta
 ## Sources
 ${manifest.sources.map((s) => `- ${s}`).join("\n")}
 
-## Cases (from ${manifestPath2})
+## Cases (from ${manifestPath3})
 ${caseList}
 
 ## Rules
 1. Each case must map to a real test file under the repo test tree.
 2. Tests should fail until implementation lands (red \u2192 green).
-3. Do not edit \`${manifestPath2}\` by hand unless fixing IDs; re-run \`fet tdd --change ${changeId}\` after planning changes.
+3. Do not edit \`${manifestPath3}\` by hand unless fixing IDs; re-run \`fet tdd --change ${changeId}\` after planning changes.
 4. When tests exist, run \`fet test --change ${changeId}\` before \`fet verify\`.
 
 Human-readable matrix: \`${specPath}\`
@@ -2320,13 +2326,13 @@ generatedAt: ${manifest.generatedAt}
 ## \u6765\u6E90
 ${manifest.sources.map((s) => `- ${s}`).join("\n")}
 
-## \u7528\u4F8B\uFF08\u89C1 ${manifestPath2}\uFF09
+## \u7528\u4F8B\uFF08\u89C1 ${manifestPath3}\uFF09
 ${caseList}
 
 ## \u89C4\u5219
 1. \u6BCF\u4E2A\u7528\u4F8B\u5FC5\u987B\u5BF9\u5E94\u4ED3\u5E93\u5185\u771F\u5B9E\u6D4B\u8BD5\u6587\u4EF6\u3002
 2. \u5B9E\u73B0\u843D\u5730\u524D\u6D4B\u8BD5\u5E94\u5904\u4E8E\u5931\u8D25\uFF08\u7EA2\uFF09\u72B6\u6001\uFF0C\u843D\u5730\u540E\u5E94\u53D8\u7EFF\u3002
-3. \u9664\u975E\u4FEE\u6B63 ID\uFF0C\u4E0D\u8981\u624B\u6539 \`${manifestPath2}\`\uFF1B\u89C4\u5212\u53D8\u66F4\u540E\u8BF7\u91CD\u65B0\u6267\u884C \`fet tdd --change ${changeId}\`\u3002
+3. \u9664\u975E\u4FEE\u6B63 ID\uFF0C\u4E0D\u8981\u624B\u6539 \`${manifestPath3}\`\uFF1B\u89C4\u5212\u53D8\u66F4\u540E\u8BF7\u91CD\u65B0\u6267\u884C \`fet tdd --change ${changeId}\`\u3002
 4. \u6D4B\u8BD5\u5C31\u7EEA\u540E\u5148 \`fet test --change ${changeId}\`\uFF0C\u518D \`fet verify\`\u3002
 
 \u53EF\u8BFB\u77E9\u9635\u89C1 \`${specPath}\`
@@ -2371,19 +2377,151 @@ function escapeTable(value) {
   return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 function renderTddApplyNextSteps(changeId, language) {
-  const manifestPath2 = tddManifestRelativePath(changeId);
+  const manifestPath3 = tddManifestRelativePath(changeId);
   if (language === "en") {
     return [
-      `Read ${manifestPath2} and tdd-instructions.md; implement code until fet test passes for this change.`,
+      `Read ${manifestPath3} and tdd-instructions.md; implement code until fet test passes for this change.`,
       `Run fet test --change ${changeId} before fet verify.`
     ];
   }
   return [
-    `\u9605\u8BFB ${manifestPath2} \u4E0E tdd-instructions.md\uFF1B\u5B9E\u73B0\u4EE3\u7801\u76F4\u81F3\u672C change \u7684 fet test \u901A\u8FC7\u3002`,
+    `\u9605\u8BFB ${manifestPath3} \u4E0E tdd-instructions.md\uFF1B\u5B9E\u73B0\u4EE3\u7801\u76F4\u81F3\u672C change \u7684 fet test \u901A\u8FC7\u3002`,
     `\u5728 fet verify \u4E4B\u524D\u5148\u6267\u884C fet test --change ${changeId}\u3002`
   ];
 }
 
+// src/visual/paths.ts
+function visualFetDirRelative(changeId) {
+  return `openspec/changes/${changeId}/.fet`;
+}
+function visualManifestRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-manifest.yaml`;
+}
+function visualSpecRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-spec.md`;
+}
+function visualInstructionsRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-instructions.md`;
+}
+function visualCaptureRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-capture.json`;
+}
+function visualResultsRelativePath(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-results.json`;
+}
+function visualBaselinesDirRelative(changeId) {
+  return `${visualFetDirRelative(changeId)}/visual-baselines`;
+}
+function visualPageScreenshotRelative(changeId, pageId) {
+  return `${visualBaselinesDirRelative(changeId)}/${pageId}/implementation.png`;
+}
+
+// src/templates/visual.ts
+function renderVisualInstructions(changeId, manifest, language) {
+  const pages = manifest.pages.map(
+    (page) => `- \`${page.id}\`: ${page.title} \u2192 \`${page.route}\` (ignore: ${page.ignoreSelectors.join(", ") || "none"})`
+  ).join("\n");
+  if (language === "en") {
+    return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: visual-instructions
+generatedAt: ${manifest.generatedAt}
+compareMode: layout-only
+---
+
+# Visual verification (layout-only)
+
+Compare **layout / spacing / shell regions** only. Do **not** pixel-match dynamic API text, list rows, or images.
+
+## Figma references
+${manifest.figmaUrls.map((url) => `- ${url}`).join("\n") || "- (none detected)"}
+
+## Pages
+${pages}
+
+## Default command
+
+\`\`\`sh
+fet visual --change ${changeId}
+\`\`\`
+
+Runs manifest refresh, capture (Playwright + \`--base-url\`), and layout checks in one step.
+
+See \`${visualSpecRelativePath(changeId)}\` for the human-readable matrix.
+`;
+  }
+  return `---
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+changeId: ${changeId}
+purpose: visual-instructions
+generatedAt: ${manifest.generatedAt}
+compareMode: layout-only
+---
+
+# \u89C6\u89C9\u9A8C\u6536\uFF08\u4EC5 layout-only\uFF09
+
+\u53EA\u9A8C\u6536 **\u6392\u7248 / \u95F4\u8DDD / \u58F3\u5C42\u533A\u57DF**\uFF0C**\u4E0D\u8981**\u5BF9\u52A8\u6001\u63A5\u53E3\u6587\u6848\u3001\u5217\u8868\u884C\u3001\u56FE\u7247\u505A\u50CF\u7D20\u7EA7\u5BF9\u6BD4\u3002
+
+## Figma \u5F15\u7528
+${manifest.figmaUrls.map((url) => `- ${url}`).join("\n") || "- \uFF08\u672A\u68C0\u6D4B\u5230\uFF09"}
+
+## \u9875\u9762
+${pages}
+
+## \u9ED8\u8BA4\u547D\u4EE4
+
+\`\`\`sh
+fet visual --change ${changeId}
+\`\`\`
+
+\u4E00\u6761\u547D\u4EE4\u5B8C\u6210\u6E05\u5355\u66F4\u65B0\u3001\u622A\u56FE\uFF08Playwright + \`--base-url\`\uFF09\u4E0E\u5E03\u5C40\u68C0\u67E5\u3002
+
+\u8BE6\u89C1 \`${visualSpecRelativePath(changeId)}\`\u3002
+`;
+}
+function renderVisualSpec(changeId, manifest, language) {
+  const rows = manifest.pages.flatMap(
+    (page) => page.checkRegions.map(
+      (region) => `| ${page.id} | ${page.route} | \`${region.selector}\` | ${region.checks.join(", ")} | ${page.ignoreSelectors.join(", ") || "-"} |`
+    )
+  ).join("\n");
+  if (language === "en") {
+    return `---
+changeId: ${changeId}
+compareMode: layout-only
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# Visual case matrix (layout-only)
+
+| Page | Route | Region | Checks | Ignored dynamic |
+|------|-------|--------|--------|-----------------|
+${rows}
+`;
+  }
+  return `---
+changeId: ${changeId}
+compareMode: layout-only
+planningFingerprint: ${manifest.planningFingerprint}
+---
+
+# \u89C6\u89C9\u7528\u4F8B\u77E9\u9635\uFF08\u4EC5 layout-only\uFF09
+
+| \u9875\u9762 | \u8DEF\u7531 | \u533A\u57DF | \u68C0\u67E5\u9879 | \u5FFD\u7565\u7684\u52A8\u6001\u533A |
+|------|------|------|--------|--------------|
+${rows}
+`;
+}
+function renderVisualVerifyNextSteps(changeId, language) {
+  if (language === "en") {
+    return [`Run fet visual --change ${changeId} before fet verify when this change references Figma.`];
+  }
+  return [`\u82E5\u672C change \u5F15\u7528 Figma\uFF0C\u8BF7\u5728 fet verify \u4E4B\u524D\u6267\u884C fet visual --change ${changeId}\u3002`];
+}
+
 // src/templates/figma-guard.ts
 var FIGMA_URL_PATTERN = /https?:\/\/(?:www\.)?figma\.com\/(?:file|design|proto)\/[^\s)\]"'<>]+/gi;
 function figmaStopHandoffRelativePath(changeId) {
@@ -3818,6 +3956,8 @@ function createChangeState(fetVersion, changeId, phase) {
     manualVerify: null,
     tdd: null,
     testRun: null,
+    visual: null,
+    visualRun: null,
     lastOpenSpecCommand: null,
     warnings: []
   };
@@ -4104,6 +4244,7 @@ async function applyWorkflowCommand(ctx, args) {
     }
     if (figmaGuard) {
       applyNextSteps.unshift(...renderFigmaApplyNextSteps(changeId, ctx.language, figmaGuard.mode));
+      applyNextSteps.splice(applyNextSteps.length - 1, 0, ...renderVisualVerifyNextSteps(changeId, ctx.language));
     }
     ctx.output.result({
       ok: true,
@@ -5043,7 +5184,7 @@ async function tddCommand(ctx) {
       cases,
       testCommand: testCommand2
     });
-    const manifestPath2 = await writeTddManifest(ctx.projectRoot, manifest);
+    const manifestPath3 = await writeTddManifest(ctx.projectRoot, manifest);
     const fetDir = join24(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
     await mkdir8(fetDir, { recursive: true });
     const instructionsPath = tddInstructionsRelativePath(changeId);
@@ -5055,7 +5196,7 @@ async function tddCommand(ctx) {
       status: "ready",
       generatedAt: manifest.generatedAt,
       planningFingerprint,
-      manifestPath: manifestPath2
+      manifestPath: manifestPath3
     };
     invalidateTestRun(changeState);
     changeState.currentPhase = "implement";
@@ -5086,7 +5227,7 @@ async function tddCommand(ctx) {
       ],
       data: {
         changeId,
-        manifestPath: manifestPath2,
+        manifestPath: manifestPath3,
         specPath,
         instructionsPath,
         caseCount: cases.length,
@@ -5291,10 +5432,674 @@ function truncate(value, max = 2e3) {
   return value.length > max ? `${value.slice(0, max)}\u2026` : value;
 }
 
+// src/commands/visual.ts
+import { mkdir as mkdir10 } from "fs/promises";
+import { join as join28 } from "path";
+
+// src/visual/config.ts
+import { readFile as readFile19 } from "fs/promises";
+import { join as join25 } from "path";
+import { parseDocument as parseDocument5 } from "yaml";
+var DEFAULT_CONFIG4 = {
+  enabled: true,
+  compareMode: "layout-only",
+  requireBeforeVerify: "when_figma",
+  whenNoCapture: "warn"
+};
+async function loadVisualConfig(projectRoot) {
+  try {
+    const raw = await readFile19(join25(projectRoot, "openspec", "config.yaml"), "utf8");
+    const doc = parseDocument5(raw);
+    const fetNode = doc.get("fet", true);
+    const node = fetNode?.get?.("visual");
+    if (!node || typeof node.get !== "function") {
+      return DEFAULT_CONFIG4;
+    }
+    const enabled = node.get("enabled");
+    const requireBeforeVerify = node.get("requireBeforeVerify");
+    const whenNoCapture = node.get("whenNoCapture");
+    return {
+      enabled: enabled === void 0 ? true : Boolean(enabled),
+      compareMode: "layout-only",
+      requireBeforeVerify: parseRequireBeforeVerify(requireBeforeVerify),
+      whenNoCapture: parseWhenNoCapture(whenNoCapture)
+    };
+  } catch {
+    return DEFAULT_CONFIG4;
+  }
+}
+function parseRequireBeforeVerify(value) {
+  if (value === "off" || value === "always" || value === "when_figma") {
+    return value;
+  }
+  return DEFAULT_CONFIG4.requireBeforeVerify;
+}
+function parseWhenNoCapture(value) {
+  if (value === "block" || value === "warn" || value === "skip") {
+    return value;
+  }
+  return DEFAULT_CONFIG4.whenNoCapture;
+}
+function isVisualRequiredForVerify(config, hasFigma) {
+  if (!config.enabled) {
+    return false;
+  }
+  if (config.requireBeforeVerify === "off") {
+    return false;
+  }
+  if (config.requireBeforeVerify === "always") {
+    return true;
+  }
+  return hasFigma;
+}
+
+// src/visual/playwright.ts
+import { createRequire } from "module";
+import { dirname as dirname9, join as join26 } from "path";
+import { pathToFileURL } from "url";
+async function resolvePlaywright(projectRoot) {
+  const require2 = createRequire(join26(projectRoot, "package.json"));
+  const candidates = ["playwright", "@playwright/test"];
+  for (const name of candidates) {
+    try {
+      const resolved = require2.resolve(name);
+      const mod = await import(pathToFileURL(resolved).href);
+      if (mod?.chromium) {
+        return mod;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+async function capturePagesWithPlaywright(projectRoot, manifest, baseUrl) {
+  const playwright = await resolvePlaywright(projectRoot);
+  if (!playwright) {
+    return [];
+  }
+  const browser = await playwright.chromium.launch({ headless: true });
+  const results = [];
+  try {
+    for (const page of manifest.pages) {
+      results.push(await captureSinglePage(projectRoot, browser, manifest.changeId, page, baseUrl));
+    }
+  } finally {
+    await browser.close();
+  }
+  return results;
+}
+async function captureSinglePage(projectRoot, browser, changeId, pageDef, baseUrl) {
+  const { mkdir: mkdir15 } = await import("fs/promises");
+  const { join: joinPath } = await import("path");
+  const screenshotRelative = visualPageScreenshotRelative(changeId, pageDef.id);
+  const screenshotAbsolute = joinPath(projectRoot, screenshotRelative);
+  await mkdir15(dirname9(screenshotAbsolute), { recursive: true });
+  const url = new URL(pageDef.route, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
+  const pwPage = await browser.newPage();
+  try {
+    await pwPage.setViewportSize(pageDef.viewport);
+    await pwPage.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
+    await pwPage.screenshot({ path: screenshotAbsolute, fullPage: true });
+    const regions = await extractRegions(pwPage, pageDef);
+    return {
+      pageId: pageDef.id,
+      route: pageDef.route,
+      screenshotPath: screenshotRelative,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      regions
+    };
+  } catch {
+    return {
+      pageId: pageDef.id,
+      route: pageDef.route,
+      screenshotPath: null,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      regions: []
+    };
+  } finally {
+    await pwPage.close();
+  }
+}
+var EXTRACT_REGIONS_SCRIPT = `
+(inputSelectors) => {
+  const layouts = [];
+  for (const selector of inputSelectors) {
+    const element = document.querySelector(selector);
+    if (!element) {
+      layouts.push({
+        selector,
+        exists: false,
+        visible: false,
+        width: 0,
+        height: 0,
+        display: "none",
+        position: "static"
+      });
+      continue;
+    }
+    const style = window.getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    layouts.push({
+      selector,
+      exists: true,
+      visible: style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0,
+      width: rect.width,
+      height: rect.height,
+      display: style.display,
+      position: style.position
+    });
+  }
+  return layouts;
+}
+`;
+async function extractRegions(page, pageDef) {
+  const selectors = pageDef.checkRegions.map((region) => region.selector);
+  return page.evaluate(EXTRACT_REGIONS_SCRIPT, selectors);
+}
+
+// src/visual/manifest.ts
+import { mkdir as mkdir9, readFile as readFile20, stat as stat11 } from "fs/promises";
+import { dirname as dirname10, join as join27 } from "path";
+import { parse as parse5, stringify as stringify4 } from "yaml";
+function visualManifestPath(projectRoot, changeId) {
+  return join27(projectRoot, visualManifestRelativePath(changeId));
+}
+async function readVisualManifest(projectRoot, changeId) {
+  const path = visualManifestPath(projectRoot, changeId);
+  try {
+    await stat11(path);
+  } catch {
+    return null;
+  }
+  const doc = parse5(await readFile20(path, "utf8"));
+  if (!doc || doc.schemaVersion !== 1 || doc.changeId !== changeId) {
+    return null;
+  }
+  return doc;
+}
+async function writeVisualManifest(projectRoot, manifest) {
+  const relative6 = visualManifestRelativePath(manifest.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, stringify4(manifest));
+  return relative6;
+}
+async function readVisualCapture(projectRoot, changeId) {
+  const path = join27(projectRoot, visualCaptureRelativePath(changeId));
+  try {
+    const doc = JSON.parse(await readFile20(path, "utf8"));
+    if (doc?.schemaVersion === 1 && doc.changeId === changeId) {
+      return doc;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function writeVisualCapture(projectRoot, capture) {
+  const relative6 = visualCaptureRelativePath(capture.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, `${JSON.stringify(capture, null, 2)}
+`);
+  return relative6;
+}
+async function writeVisualResults(projectRoot, results) {
+  const relative6 = visualResultsRelativePath(results.changeId);
+  const path = join27(projectRoot, relative6);
+  await mkdir9(dirname10(path), { recursive: true });
+  await atomicWrite(path, `${JSON.stringify(results, null, 2)}
+`);
+  return relative6;
+}
+function createVisualManifest(input) {
+  return {
+    schemaVersion: 1,
+    changeId: input.changeId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    fetVersion: FET_VERSION,
+    planningFingerprint: input.planningFingerprint,
+    compareMode: "layout-only",
+    figmaUrls: input.figmaUrls,
+    figmaSources: input.figmaSources,
+    run: { baseUrl: input.baseUrl },
+    pages: input.pages
+  };
+}
+
+// src/visual/capture.ts
+async function runVisualCapture(options) {
+  const warnings = [];
+  const baseUrl = options.baseUrl ?? options.manifest.run.baseUrl;
+  if (!baseUrl) {
+    return handleMissingBaseUrl(options.config, options.language, warnings);
+  }
+  const playwright = await resolvePlaywright(options.projectRoot);
+  if (!playwright) {
+    return handleMissingPlaywright(options.config, options.language, warnings);
+  }
+  const pages = await capturePagesWithPlaywright(options.projectRoot, options.manifest, baseUrl);
+  const failedPages = pages.filter((page) => !page.screenshotPath);
+  const capture = {
+    schemaVersion: 1,
+    changeId: options.changeId,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    baseUrl,
+    pages
+  };
+  await writeVisualCapture(options.projectRoot, capture);
+  if (failedPages.length) {
+    return {
+      status: "failed",
+      capture,
+      warnings,
+      message: options.language === "en" ? `Capture failed for ${failedPages.length} page(s). Check dev server and routes.` : `${failedPages.length} \u4E2A\u9875\u9762\u622A\u56FE\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5 dev \u670D\u52A1\u4E0E\u8DEF\u7531\u3002`
+    };
+  }
+  return { status: "passed", capture, warnings };
+}
+function handleMissingBaseUrl(config, language, warnings) {
+  const message = language === "en" ? "No base URL for capture. Pass --base-url or set manifest.run.baseUrl." : "\u672A\u914D\u7F6E base URL\uFF0C\u65E0\u6CD5\u622A\u56FE\u3002\u8BF7\u4F7F\u7528 --base-url \u6216\u5728 manifest \u4E2D\u8BBE\u7F6E run.baseUrl\u3002";
+  warnings.push(message);
+  if (config.whenNoCapture === "block") {
+    return { status: "failed", capture: null, warnings, message };
+  }
+  return { status: "skipped", capture: null, warnings, message };
+}
+function handleMissingPlaywright(config, language, warnings) {
+  const message = language === "en" ? "Playwright not found in project. Install playwright or use --check-layout-only after manual capture." : "\u9879\u76EE\u672A\u5B89\u88C5 Playwright\u3002\u8BF7\u5B89\u88C5 playwright\uFF0C\u6216\u5728\u624B\u52A8\u622A\u56FE\u540E\u4F7F\u7528 --check-layout-only\u3002";
+  warnings.push(message);
+  if (config.whenNoCapture === "block") {
+    return { status: "failed", capture: null, warnings, message };
+  }
+  return { status: "skipped", capture: null, warnings, message };
+}
+
+// src/visual/check-layout.ts
+function runLayoutCheck(manifest, capture, language, options) {
+  const regions = [];
+  if (!capture && options?.allowManifestOnly) {
+    return runManifestOnlyValidation(manifest, language);
+  }
+  if (capture?.pages.length) {
+    for (const page of manifest.pages) {
+      const captured = capture.pages.find((item) => item.pageId === page.id);
+      for (const region of page.checkRegions) {
+        const layout = captured?.regions.find((item) => item.selector === region.selector);
+        const result = evaluateRegion(page.id, region.selector, region.checks, layout, language);
+        regions.push(result);
+      }
+    }
+  } else {
+    for (const page of manifest.pages) {
+      if (!page.checkRegions.length) {
+        regions.push({
+          pageId: page.id,
+          selector: "(page)",
+          status: "failed",
+          message: language === "en" ? "No checkRegions defined" : "\u672A\u5B9A\u4E49 checkRegions"
+        });
+        continue;
+      }
+      for (const region of page.checkRegions) {
+        regions.push({
+          pageId: page.id,
+          selector: region.selector,
+          status: capture ? "failed" : "skipped",
+          message: language === "en" ? "No capture data; run capture with --base-url or install Playwright" : "\u65E0\u622A\u56FE\u6570\u636E\uFF1B\u8BF7\u5E26 --base-url \u8FD0\u884C capture \u6216\u5B89\u88C5 Playwright"
+        });
+      }
+    }
+  }
+  const failed = regions.filter((item) => item.status === "failed");
+  if (failed.length) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? `Layout check failed for ${failed.length} region(s).` : `${failed.length} \u4E2A\u533A\u57DF\u7684\u5E03\u5C40\u68C0\u67E5\u672A\u901A\u8FC7\u3002`
+    };
+  }
+  const skipped = regions.filter((item) => item.status === "skipped");
+  if (skipped.length && !capture) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? "Layout check requires capture data when regions are defined." : "\u5DF2\u5B9A\u4E49\u68C0\u67E5\u533A\u57DF\u65F6\u9700\u8981 capture \u6570\u636E\u624D\u80FD\u5B8C\u6210\u5E03\u5C40\u9A8C\u6536\u3002"
+    };
+  }
+  return { status: "passed", regions };
+}
+function runManifestOnlyValidation(manifest, language) {
+  const regions = [];
+  if (!manifest.pages.length) {
+    return {
+      status: "failed",
+      regions,
+      message: language === "en" ? "Visual manifest has no pages." : "\u89C6\u89C9\u6E05\u5355\u4E2D\u6CA1\u6709\u4EFB\u4F55\u9875\u9762\u3002"
+    };
+  }
+  for (const page of manifest.pages) {
+    for (const region of page.checkRegions) {
+      regions.push({
+        pageId: page.id,
+        selector: region.selector,
+        status: "skipped",
+        message: language === "en" ? "Manifest-only mode (layout-only, no pixel/content compare)" : "\u4EC5 manifest \u6821\u9A8C\uFF08layout-only\uFF0C\u4E0D\u5BF9\u6BD4\u50CF\u7D20/\u52A8\u6001\u5185\u5BB9\uFF09"
+      });
+    }
+  }
+  return {
+    status: "passed",
+    regions,
+    message: language === "en" ? "Manifest validated; capture skipped \u2014 layout-only checklist recorded." : "\u6E05\u5355\u6821\u9A8C\u901A\u8FC7\uFF1B\u5DF2\u8DF3\u8FC7\u622A\u56FE \u2014 \u5DF2\u8BB0\u5F55 layout-only \u68C0\u67E5\u9879\u3002"
+  };
+}
+function evaluateRegion(pageId, selector, checks, layout, language) {
+  if (!layout) {
+    return {
+      pageId,
+      selector,
+      status: "failed",
+      message: language === "en" ? "Region not found in capture" : "capture \u4E2D\u672A\u627E\u5230\u8BE5\u533A\u57DF"
+    };
+  }
+  for (const check of checks) {
+    if (check === "exists" && !layout.exists) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Missing element" : "\u5143\u7D20\u4E0D\u5B58\u5728" };
+    }
+    if (check === "visible" && !layout.visible) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Not visible" : "\u4E0D\u53EF\u89C1" };
+    }
+    if (check === "has-box" && (layout.width <= 0 || layout.height <= 0)) {
+      return { pageId, selector, status: "failed", message: language === "en" ? "Zero layout box" : "\u5E03\u5C40\u5C3A\u5BF8\u4E3A 0" };
+    }
+  }
+  return { pageId, selector, status: "passed" };
+}
+function buildVisualResults(input) {
+  return {
+    schemaVersion: 1,
+    changeId: input.changeId,
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint: input.planningFingerprint,
+    steps: input.steps,
+    captureStatus: input.captureStatus,
+    layoutStatus: input.layoutStatus,
+    regions: input.regions
+  };
+}
+
+// src/visual/generate.ts
+var DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+async function buildVisualManifestPages(projectRoot, changeId, figmaUrls) {
+  if (figmaUrls.length) {
+    return [
+      {
+        id: `${changeId}-main`,
+        title: "Main UI screen",
+        route: "/",
+        viewport: DEFAULT_VIEWPORT,
+        dataMode: "mock",
+        mockFixture: null,
+        ignoreSelectors: [".dynamic-list", "[data-dynamic]", "[data-testid='dynamic-content']"],
+        checkRegions: [
+          { selector: "header, [role='banner'], .app-header", checks: ["exists", "visible", "has-box"] },
+          { selector: "main, [role='main'], .app-main", checks: ["exists", "visible", "has-box"] },
+          { selector: "nav, [role='navigation'], .app-nav", checks: ["exists", "has-box"] }
+        ]
+      }
+    ];
+  }
+  return [
+    {
+      id: `${changeId}-shell`,
+      title: "Application shell",
+      route: "/",
+      viewport: DEFAULT_VIEWPORT,
+      dataMode: "mock",
+      mockFixture: null,
+      ignoreSelectors: [".dynamic-list", "[data-dynamic]"],
+      checkRegions: [{ selector: "body", checks: ["exists", "visible", "has-box"] }]
+    }
+  ];
+}
+async function generateVisualManifestInput(projectRoot, changeId, baseUrl) {
+  const { urls, sources } = await collectFigmaUrlsFromChange(projectRoot, changeId);
+  const planningFingerprint = await computePlanningFingerprint(projectRoot, changeId);
+  const pages = await buildVisualManifestPages(projectRoot, changeId, urls);
+  return {
+    planningFingerprint,
+    figmaUrls: urls,
+    figmaSources: sources,
+    pages
+  };
+}
+function mergeBaseUrl(manifest, baseUrl) {
+  if (!baseUrl) {
+    return manifest;
+  }
+  return {
+    ...manifest,
+    run: { baseUrl }
+  };
+}
+
+// src/visual/gates.ts
+async function assertVisualPassed(ctx, changeId) {
+  const config = await loadVisualConfig(ctx.projectRoot);
+  const { urls } = await collectFigmaUrlsFromChange(ctx.projectRoot, changeId);
+  if (!isVisualRequiredForVerify(config, urls.length > 0)) {
+    return;
+  }
+  const change = await ctx.stateStore.readChange(changeId);
+  const visualRun = change?.visualRun;
+  if (visualRun?.status === "skipped") {
+    return;
+  }
+  if (visualRun?.status === "passed" && await fingerprintMatches2(ctx, changeId, visualRun)) {
+    return;
+  }
+  throw new FetError({
+    code: "STATE_CORRUPTED" /* StateCorrupted */,
+    message: msg(ctx.language, "\u672C change \u5C1A\u672A\u901A\u8FC7 fet visual\u3002", "This change has not passed fet visual yet."),
+    details: { changeId, visualRun: visualRun ?? null, figmaUrlCount: urls.length },
+    suggestedCommand: `fet visual --change ${changeId}`,
+    recoverable: true
+  });
+}
+async function fingerprintMatches2(ctx, changeId, visualRun) {
+  const current = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  return visualRun.planningFingerprint === current;
+}
+function invalidateVisualRun(state) {
+  state.visualRun = null;
+}
+function manifestPath2(changeId) {
+  return visualManifestRelativePath(changeId);
+}
+
+// src/commands/visual.ts
+async function visualCommand(ctx, options) {
+  await withProjectLock(ctx.projectRoot, { command: "visual", cwd: ctx.cwd, fetVersion: ctx.fetVersion }, async () => {
+    const changeId = await resolveChangeId(ctx);
+    await assertChangeExists(ctx, changeId);
+    const config = await loadVisualConfig(ctx.projectRoot);
+    const steps = [];
+    const warnings = [];
+    const manifest = await ensureManifest(ctx, changeId, options.baseUrl ?? null);
+    steps.push("manifest");
+    if (options.plan) {
+      ctx.output.result({
+        ok: true,
+        command: "visual",
+        summary: msg(ctx.language, "\u5DF2\u751F\u6210 fet visual \u6267\u884C\u8BA1\u5212\u3002", "Generated fet visual execution plan."),
+        data: {
+          changeId,
+          compareMode: manifest.compareMode,
+          steps: options.checkLayoutOnly ? ["manifest", "check-layout"] : options.captureOnly ? ["manifest", "capture"] : ["manifest", "capture", "check-layout"],
+          baseUrl: options.baseUrl ?? manifest.run.baseUrl,
+          pages: manifest.pages.map((page) => ({ id: page.id, route: page.route }))
+        },
+        nextSteps: [`fet visual --change ${changeId}${options.baseUrl ? ` --base-url ${options.baseUrl}` : ""}`]
+      });
+      return;
+    }
+    let captureStatus = "skipped";
+    let captureDoc = await readVisualCapture(ctx.projectRoot, changeId);
+    if (!options.checkLayoutOnly) {
+      const captureResult = await runVisualCapture({
+        projectRoot: ctx.projectRoot,
+        changeId,
+        manifest,
+        baseUrl: options.baseUrl ?? null,
+        config,
+        language: ctx.language
+      });
+      warnings.push(...captureResult.warnings);
+      captureStatus = captureResult.status;
+      captureDoc = captureResult.capture;
+      steps.push("capture");
+      if (captureResult.status === "failed") {
+        await recordVisualFailure(ctx, changeId, manifest.planningFingerprint, steps, captureStatus, "failed", [], captureResult.message);
+        throw new FetError({
+          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+          message: captureResult.message ?? msg(ctx.language, "fet visual \u622A\u56FE\u5931\u8D25\u3002", "fet visual capture failed."),
+          details: { changeId },
+          suggestedCommand: `fet visual --change ${changeId} --base-url http://localhost:3000`,
+          recoverable: true
+        });
+      }
+    } else {
+      steps.push("capture");
+      captureStatus = captureDoc ? "passed" : "skipped";
+    }
+    if (!options.captureOnly) {
+      const layout = runLayoutCheck(manifest, captureDoc, ctx.language, {
+        allowManifestOnly: captureStatus === "skipped" && config.whenNoCapture !== "block"
+      });
+      steps.push("check-layout");
+      const results = buildVisualResults({
+        changeId,
+        planningFingerprint: manifest.planningFingerprint,
+        steps,
+        captureStatus,
+        layoutStatus: layout.status,
+        regions: layout.regions
+      });
+      const resultsPath = await writeVisualResults(ctx.projectRoot, results);
+      if (layout.status === "failed") {
+        await recordVisualFailure(ctx, changeId, manifest.planningFingerprint, steps, captureStatus, layout.status, layout.regions, layout.message);
+        throw new FetError({
+          code: "OPENSPEC_COMMAND_FAILED" /* OpenSpecCommandFailed */,
+          message: layout.message ?? msg(ctx.language, "fet visual \u5E03\u5C40\u68C0\u67E5\u672A\u901A\u8FC7\u3002", "fet visual layout check failed."),
+          details: { changeId, resultsPath: visualResultsRelativePath(changeId) },
+          suggestedCommand: `fet visual --change ${changeId}`,
+          recoverable: true
+        });
+      }
+      await recordVisualSuccess(ctx, changeId, manifest.planningFingerprint, resultsPath, captureStatus);
+      ctx.output.result({
+        ok: true,
+        command: "visual",
+        summary: msg(
+          ctx.language,
+          `change "${changeId}" \u5DF2\u901A\u8FC7 layout-only \u89C6\u89C9\u9A8C\u6536\u3002`,
+          `Layout-only visual verification passed for change "${changeId}".`
+        ),
+        warnings: warnings.length ? warnings : void 0,
+        nextSteps: [`fet verify --change ${changeId}`],
+        data: { changeId, results, capturePath: captureDoc ? visualCaptureRelativePath(changeId) : null }
+      });
+      return;
+    }
+    ctx.output.result({
+      ok: true,
+      command: "visual",
+      summary: msg(ctx.language, "fet visual \u622A\u56FE\u6B65\u9AA4\u5DF2\u5B8C\u6210\u3002", "fet visual capture step completed."),
+      warnings: warnings.length ? warnings : void 0,
+      data: { changeId, captureStatus, capturePath: captureDoc ? visualCaptureRelativePath(changeId) : null }
+    });
+  });
+}
+async function ensureManifest(ctx, changeId, baseUrl) {
+  const fingerprint2 = await computePlanningFingerprint(ctx.projectRoot, changeId);
+  const existing = await readVisualManifest(ctx.projectRoot, changeId);
+  if (existing && existing.planningFingerprint === fingerprint2 && (!baseUrl || existing.run.baseUrl === baseUrl)) {
+    return existing;
+  }
+  const input = await generateVisualManifestInput(ctx.projectRoot, changeId, baseUrl);
+  const manifest = mergeBaseUrl(
+    createVisualManifest({
+      changeId,
+      planningFingerprint: input.planningFingerprint,
+      figmaUrls: input.figmaUrls,
+      figmaSources: input.figmaSources,
+      baseUrl,
+      pages: input.pages
+    }),
+    baseUrl
+  );
+  await writeVisualManifest(ctx.projectRoot, manifest);
+  const fetDir = join28(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  await mkdir10(fetDir, { recursive: true });
+  await atomicWrite(join28(ctx.projectRoot, visualInstructionsRelativePath(changeId)), renderVisualInstructions(changeId, manifest, ctx.language));
+  await atomicWrite(join28(ctx.projectRoot, visualSpecRelativePath(changeId)), renderVisualSpec(changeId, manifest, ctx.language));
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visual = {
+    status: "ready",
+    generatedAt: manifest.generatedAt,
+    planningFingerprint: fingerprint2,
+    manifestPath: manifestPath2(changeId)
+  };
+  invalidateVisualRun(changeState);
+  await ctx.stateStore.writeChange(changeState);
+  return manifest;
+}
+async function recordVisualSuccess(ctx, changeId, planningFingerprint, resultsPath, captureStatus) {
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visualRun = {
+    status: "passed",
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint,
+    manifestPath: manifestPath2(changeId),
+    resultsPath,
+    captureStatus
+  };
+  await ctx.stateStore.writeChange(changeState);
+}
+async function recordVisualFailure(ctx, changeId, planningFingerprint, steps, captureStatus, layoutStatus, regions, message) {
+  const results = buildVisualResults({
+    changeId,
+    planningFingerprint,
+    steps,
+    captureStatus,
+    layoutStatus,
+    regions
+  });
+  await writeVisualResults(ctx.projectRoot, results);
+  const changeState = await ctx.stateStore.getOrCreateChange(changeId, "verify");
+  changeState.visualRun = {
+    status: "failed",
+    ranAt: (/* @__PURE__ */ new Date()).toISOString(),
+    compareMode: "layout-only",
+    planningFingerprint,
+    manifestPath: manifestPath2(changeId),
+    resultsPath: visualResultsRelativePath(changeId),
+    captureStatus
+  };
+  await ctx.stateStore.writeChange(changeState);
+  if (message) {
+    void message;
+  }
+}
+
 // src/commands/verify.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir9, readFile as readFile19, stat as stat11 } from "fs/promises";
-import { join as join25 } from "path";
+import { mkdir as mkdir11, readFile as readFile21, stat as stat12 } from "fs/promises";
+import { join as join29 } from "path";
 async function verifyCommand(ctx, options) {
   if (options.auto) {
     const scan = await ctx.scanner.scan(ctx.projectRoot, {});
@@ -5361,10 +6166,11 @@ async function verifyCommand(ctx, options) {
 async function writeInstructions(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   await assertTestPassed(ctx, changeId);
+  await assertVisualPassed(ctx, changeId);
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const dir = join25(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
-  const instructionsPath = join25(dir, "verify-instructions.md");
-  await mkdir9(dir, { recursive: true });
+  const dir = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet");
+  const instructionsPath = join29(dir, "verify-instructions.md");
+  await mkdir11(dir, { recursive: true });
   await atomicWrite(instructionsPath, renderVerifyInstructions(changeId, generatedAt));
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
   state.currentPhase = "verify";
@@ -5380,8 +6186,9 @@ async function writeInstructions(ctx, changeId) {
 async function markDone(ctx, changeId) {
   await assertChangeExists(ctx, changeId);
   await assertTestPassed(ctx, changeId);
+  await assertVisualPassed(ctx, changeId);
   const declaredAt = (/* @__PURE__ */ new Date()).toISOString();
-  const instructionsPath = join25(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
+  const instructionsPath = join29(ctx.projectRoot, "openspec", "changes", changeId, ".fet", "verify-instructions.md");
   const instructions = await readInstructions(ctx, instructionsPath, changeId);
   const instructionsGeneratedAt = readFrontMatterValue(instructions, "generatedAt") ?? declaredAt;
   const state = await ctx.stateStore.getOrCreateChange(changeId, "verify");
@@ -5405,8 +6212,8 @@ async function markDone(ctx, changeId) {
 }
 async function readInstructions(ctx, path, changeId) {
   try {
-    await stat11(path);
-    const content = await readFile19(path, "utf8");
+    await stat12(path);
+    const content = await readFile21(path, "utf8");
     const fileChangeId = readFrontMatterValue(content, "changeId");
     if (fileChangeId !== changeId) {
       throw new FetError({
@@ -5529,12 +6336,12 @@ function renderIdeModelPolicy(command, language = "zh-CN") {
 import { resolve } from "path";
 
 // src/adapters/codex/index.ts
-import { mkdir as mkdir10, readFile as readFile20, stat as stat12 } from "fs/promises";
+import { mkdir as mkdir12, readFile as readFile22, stat as stat13 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname9, join as join26 } from "path";
+import { dirname as dirname11, join as join30 } from "path";
 
 // src/adapters/commands.ts
-var FET_STANDALONE_COMMANDS = ["tdd", "test"];
+var FET_STANDALONE_COMMANDS = ["tdd", "test", "visual"];
 var FET_WORKFLOW_COMMANDS = [
   "explore",
   "propose",
@@ -6617,7 +7424,7 @@ var CodexAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists6(join26(projectRoot, ".codex")) || await exists6(join26(projectRoot, "AGENTS.md")),
+      detected: await exists6(join30(projectRoot, ".codex")) || await exists6(join30(projectRoot, "AGENTS.md")),
       reason: "Codex adapter is available for projects that use AGENTS.md"
     };
   }
@@ -6656,7 +7463,7 @@ var CodexAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir10(dirname9(target), { recursive: true });
+      await mkdir12(dirname11(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(displayPath);
     }
@@ -6683,9 +7490,9 @@ var CodexAdapter = class {
 };
 function resolveTarget(projectRoot, file) {
   if (file.root === "codex-home") {
-    return join26(resolveCodexHome(), file.path);
+    return join30(resolveCodexHome(), file.path);
   }
-  return join26(projectRoot, file.path);
+  return join30(projectRoot, file.path);
 }
 function displayPathFor(file) {
   if (file.root === "codex-home") {
@@ -6694,18 +7501,18 @@ function displayPathFor(file) {
   return file.path;
 }
 function resolveCodexHome() {
-  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join26(homedir(), ".codex");
+  return process.env.FET_CODEX_HOME ?? process.env.CODEX_HOME ?? join30(homedir(), ".codex");
 }
 async function readExisting(path) {
   try {
-    return await readFile20(path, "utf8");
+    return await readFile22(path, "utf8");
   } catch {
     return null;
   }
 }
 async function exists6(path) {
   try {
-    await stat12(path);
+    await stat13(path);
     return true;
   } catch {
     return false;
@@ -6713,8 +7520,8 @@ async function exists6(path) {
 }
 
 // src/adapters/cursor/index.ts
-import { mkdir as mkdir11, readFile as readFile21, stat as stat13 } from "fs/promises";
-import { dirname as dirname10, join as join27 } from "path";
+import { mkdir as mkdir13, readFile as readFile23, stat as stat14 } from "fs/promises";
+import { dirname as dirname12, join as join31 } from "path";
 
 // src/adapters/cursor/templates.ts
 function cursorFigmaStopRuleFile(language = DEFAULT_LANGUAGE) {
@@ -6849,6 +7656,9 @@ After installation, verify with \`gitnexus --version\`, then run \`fet graph ini
   if (command === "tdd" || command === "test") {
     return renderTddTestSkill(command, usage, language);
   }
+  if (command === "visual") {
+    return renderVisualSkill(usage, language);
+  }
   if (command === "propose" || command === "continue" || command === "ff") {
     return renderPlanningSkill(command, usage, language);
   }
@@ -6970,6 +7780,35 @@ ${uiContractBlock}
 \u5B9E\u65BD\u524D\u987B\u5DF2\u8FD0\u884C \`fet tdd\`\uFF1B\u5B58\u5728 \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\` \u65F6\u6309\u6E05\u5355\u7F16\u5199\u6D4B\u8BD5\u4E0E\u5B9E\u73B0\uFF0C\u5E76\u5728 \`fet verify\` \u524D\u5148 \`fet test\`\u3002
 `;
 }
+function renderVisualSkill(usage, language) {
+  const body = language === "en" ? `Default \`fet visual\` runs manifest refresh, Playwright capture (needs \`--base-url\`), and **layout-only** checks (no pixel match on dynamic API content). Use \`--plan\`, \`--capture-only\`, or \`--check-layout-only\` only when debugging.` : `\u9ED8\u8BA4 \`fet visual\` \u4F1A\u66F4\u65B0\u6E05\u5355\u3001Playwright \u622A\u56FE\uFF08\u9700 \`--base-url\`\uFF09\u5E76\u505A **layout-only** \u68C0\u67E5\uFF08\u4E0D\u5BF9\u52A8\u6001\u63A5\u53E3\u5185\u5BB9\u505A\u50CF\u7D20\u5BF9\u6BD4\uFF09\u3002\u4EC5\u5728\u8C03\u8BD5\u65F6\u4F7F\u7528 \`--plan\`\u3001\`--capture-only\`\u3001\`--check-layout-only\`\u3002`;
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: cursor-adapter
+adapterVersion: 1
+command: ${usage}
+FET:END -->
+
+---
+name: fet-visual
+description: ${language === "en" ? "Layout-only visual verification for a change" : "change \u7EA7 layout-only \u89C6\u89C9\u9A8C\u6536"}
+disable-model-invocation: true
+---
+
+${renderIdeModelPolicy("visual", language)}
+
+${languageInstruction(language)}
+
+\u8BF7\u5728\u7EC8\u7AEF\u4E2D\u6267\u884C\uFF1A
+
+\`\`\`sh
+${usage}
+\`\`\`
+
+${body}
+`;
+}
 function renderTddTestSkill(command, usage, language) {
   const description = command === "tdd" ? language === "en" ? "Generate per-change TDD manifest and test instructions" : "\u751F\u6210\u672C change \u7684 TDD \u6E05\u5355\u4E0E\u6D4B\u8BD5\u6307\u5F15" : language === "en" ? "Run unit tests scoped to the change TDD manifest" : "\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B";
   const body = command === "tdd" ? language === "en" ? `After planning artifacts exist, run this before \`fet apply\`. It writes \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\`, \`tdd-spec.md\`, and \`tdd-instructions.md\`. Then create failing tests in the repo before implementation.` : `\u89C4\u5212\u4EA7\u7269\u5C31\u7EEA\u540E\u3001\`fet apply\` \u4E4B\u524D\u8FD0\u884C\u3002\u4F1A\u5199\u5165 \`openspec/changes/<change-id>/.fet/tdd-manifest.yaml\`\u3001\`tdd-spec.md\`\u3001\`tdd-instructions.md\`\uFF0C\u518D\u5728\u4ED3\u5E93\u4E2D\u7F16\u5199\u9884\u671F\u5931\u8D25\u7684\u6D4B\u8BD5\u3002` : language === "en" ? `Run after implementation. Requires a current \`tdd-manifest.yaml\`. Records pass/fail in FET state; \`fet verify\` is blocked until this passes (unless configured to skip).` : `\u5B9E\u73B0\u5B8C\u6210\u540E\u8FD0\u884C\u3002\u9700\u8981\u6709\u6548\u7684 \`tdd-manifest.yaml\`\u3002\u7ED3\u679C\u5199\u5165 FET \u72B6\u6001\uFF1B\u672A\u901A\u8FC7\u524D \`fet verify\` \u4F1A\u88AB\u62E6\u622A\uFF08\u9664\u975E\u914D\u7F6E\u4E3A skip\uFF09\u3002`;
@@ -7007,7 +7846,7 @@ var CursorAdapter = class {
   adapterVersion = 1;
   async detect(projectRoot) {
     return {
-      detected: await exists7(join27(projectRoot, ".cursor")),
+      detected: await exists7(join31(projectRoot, ".cursor")),
       reason: "Cursor adapter is available for any project"
     };
   }
@@ -7024,7 +7863,7 @@ var CursorAdapter = class {
     const written = [];
     const skipped = [];
     for (const file of plan.files) {
-      const target = join27(projectRoot, file.path);
+      const target = join31(projectRoot, file.path);
       const existing = await readExisting2(target);
       if (existing && !existing.includes("FET:MANAGED") && !force) {
         throw new FetError({
@@ -7037,7 +7876,7 @@ var CursorAdapter = class {
       if (existing && !existing.includes("FET:MANAGED") && force) {
         await createBackup(target);
       }
-      await mkdir11(dirname10(target), { recursive: true });
+      await mkdir13(dirname12(target), { recursive: true });
       await atomicWrite(target, file.content);
       written.push(file.path);
     }
@@ -7047,7 +7886,7 @@ var CursorAdapter = class {
     const plan = await this.planInstall(projectRoot);
     const checks = [];
     for (const file of plan.files) {
-      const target = join27(projectRoot, file.path);
+      const target = join31(projectRoot, file.path);
       const content = await readExisting2(target);
       const managed = Boolean(content?.includes("FET:MANAGED"));
       const versionMatches = Boolean(content?.includes(`adapterVersion: ${this.adapterVersion}`));
@@ -7063,14 +7902,14 @@ var CursorAdapter = class {
 };
 async function readExisting2(path) {
   try {
-    return await readFile21(path, "utf8");
+    return await readFile23(path, "utf8");
   } catch {
     return null;
   }
 }
 async function exists7(path) {
   try {
-    await stat13(path);
+    await stat14(path);
     return true;
   } catch {
     return false;
@@ -7082,13 +7921,13 @@ import { execFile as execFile4 } from "child_process";
 import { promisify as promisify4 } from "util";
 
 // src/openspec/inspector.ts
-import { readdir as readdir6, stat as stat14 } from "fs/promises";
-import { join as join28 } from "path";
+import { readdir as readdir6, stat as stat15 } from "fs/promises";
+import { join as join32 } from "path";
 async function inspectOpenSpecProject(projectRoot) {
-  const openspecPath = join28(projectRoot, "openspec");
-  const changesPath = join28(openspecPath, "changes");
-  const legacyArchivePath = join28(openspecPath, "archive");
-  const changesArchivePath = join28(changesPath, "archive");
+  const openspecPath = join32(projectRoot, "openspec");
+  const changesPath = join32(openspecPath, "changes");
+  const legacyArchivePath = join32(openspecPath, "archive");
+  const changesArchivePath = join32(changesPath, "archive");
   return {
     exists: await exists8(openspecPath),
     changes: await listDirectories(changesPath, { exclude: ["archive"] }),
@@ -7096,13 +7935,13 @@ async function inspectOpenSpecProject(projectRoot) {
   };
 }
 async function inspectOpenSpecChange(projectRoot, changeId) {
-  const changePath = join28(projectRoot, "openspec", "changes", changeId);
-  const tasksPath = join28(changePath, "tasks.md");
-  const specsPath = join28(changePath, "specs");
+  const changePath = join32(projectRoot, "openspec", "changes", changeId);
+  const tasksPath = join32(changePath, "tasks.md");
+  const specsPath = join32(changePath, "specs");
   return {
     changeId,
     exists: await exists8(changePath),
-    hasProposal: await exists8(join28(changePath, "proposal.md")),
+    hasProposal: await exists8(join32(changePath, "proposal.md")),
     hasTasks: await exists8(tasksPath),
     hasSpecs: await exists8(specsPath),
     tasksPath,
@@ -7120,7 +7959,7 @@ async function listDirectories(path, options = {}) {
 }
 async function exists8(path) {
   try {
-    await stat14(path);
+    await stat15(path);
     return true;
   } catch {
     return false;
@@ -7303,13 +8142,13 @@ function escapeRegExp(value) {
 }
 
 // src/scanner/routes.ts
-import { readdir as readdir7, stat as stat15 } from "fs/promises";
-import { join as join29, relative as relative5, sep } from "path";
+import { readdir as readdir7, stat as stat16 } from "fs/promises";
+import { join as join33, relative as relative5, sep } from "path";
 async function scanRoutes(projectRoot) {
   const candidates = ["src/routes", "src/pages", "app", "pages"];
   const routes = [];
   for (const candidate of candidates) {
-    const root = join29(projectRoot, candidate);
+    const root = join33(projectRoot, candidate);
     if (!await exists9(root)) {
       continue;
     }
@@ -7337,7 +8176,7 @@ async function listFiles(root) {
   const entries = await readdir7(root, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const path = join29(root, entry.name);
+    const path = join33(root, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(path));
     } else {
@@ -7348,7 +8187,7 @@ async function listFiles(root) {
 }
 async function exists9(path) {
   try {
-    await stat15(path);
+    await stat16(path);
     return true;
   } catch {
     return false;
@@ -7505,9 +8344,9 @@ async function createCommandContext(command, options) {
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/update/check.ts
-import { mkdir as mkdir12, readFile as readFile22, writeFile } from "fs/promises";
+import { mkdir as mkdir14, readFile as readFile24, writeFile } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname11, join as join30 } from "path";
+import { dirname as dirname13, join as join34 } from "path";
 var DEFAULT_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
 function getFetUpdateCheckMode(env = process.env) {
   const value = env.FET_UPDATE_CHECK?.trim().toLowerCase();
@@ -7580,11 +8419,11 @@ function formatFetUpdateWarning(availability, language) {
 }
 function cachePath() {
   const home = process.env.FET_UPDATE_CHECK_CACHE_HOME?.trim() || homedir2();
-  return join30(home, ".fet", "update-check-cache.json");
+  return join34(home, ".fet", "update-check-cache.json");
 }
 async function readUpdateCheckCache() {
   try {
-    const raw = await readFile22(cachePath(), "utf8");
+    const raw = await readFile24(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.latestVersion !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -7600,7 +8439,7 @@ async function readUpdateCheckCache() {
 }
 async function writeUpdateCheckCache(cache) {
   const path = cachePath();
-  await mkdir12(dirname11(path), { recursive: true });
+  await mkdir14(dirname13(path), { recursive: true });
   await writeFile(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
 }
@@ -7691,6 +8530,19 @@ addGlobalOptions(program.command("tdd").description("\u6839\u636E\u89C4\u5212\u4
 addGlobalOptions(program.command("test").description("\u6309 change TDD \u6E05\u5355\u8FD0\u884C\u5355\u6D4B\u5E76\u8BB0\u5F55\u7EFF\u706F\u72B6\u6001").option("--plan", "\u4EC5\u8F93\u51FA\u5C06\u6267\u884C\u7684\u6D4B\u8BD5\u547D\u4EE4\uFF0C\u4E0D\u8FD0\u884C")).action(
   wrap("test", (ctx, options) => testCommand(ctx, { plan: Boolean(options.plan) }))
 );
+addGlobalOptions(
+  program.command("visual").description("layout-only \u89C6\u89C9\u9A8C\u6536\uFF08\u9ED8\u8BA4\uFF1A\u66F4\u65B0\u6E05\u5355 + \u622A\u56FE + \u5E03\u5C40\u68C0\u67E5\uFF09").option("--plan", "\u4EC5\u8F93\u51FA\u6267\u884C\u8BA1\u5212").option("--capture-only", "\u4EC5\u6267\u884C\u622A\u56FE").option("--check-layout-only", "\u4EC5\u6267\u884C\u5E03\u5C40\u68C0\u67E5\uFF08\u4F9D\u8D56\u5DF2\u6709 capture\uFF09").option("--base-url <url>", "\u5E94\u7528 base URL\uFF0C\u7528\u4E8E Playwright \u622A\u56FE")
+).action(
+  wrap(
+    "visual",
+    (ctx, options) => visualCommand(ctx, {
+      plan: Boolean(options.plan),
+      captureOnly: Boolean(options.captureOnly),
+      checkLayoutOnly: Boolean(options.checkLayoutOnly),
+      baseUrl: options.baseUrl
+    })
+  )
+);
 addGlobalOptions(program.command("verify").description("\u6700\u7EC8\u8D28\u91CF\u9A8C\u8BC1").option("--done", "\u58F0\u660E\u624B\u52A8\u9A8C\u8BC1\u5DF2\u5B8C\u6210").option("--auto", "\u751F\u6210\u6216\u6267\u884C\u81EA\u52A8\u9A8C\u8BC1\u8BA1\u5212")).action(
   wrap("verify", verifyCommand)
 );