create-yss-spec 3.0.1 → 3.1.0

package/template/.codex/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseDocument, stringify } from "../../../../scripts/vendor/yaml.mjs";
+
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const CASE_ID = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+
+const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+const digest = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+
+function required(data, field, parent, errors) {
+  if (!object(data) || data[field] === undefined || data[field] === null) errors.push(`${parent}.${field} 缺失`);
+}
+
+function requiredString(data, field, parent, errors) {
+  required(data, field, parent, errors);
+  if (object(data) && data[field] !== undefined && !nonEmpty(data[field])) errors.push(`${parent}.${field} 必须是非空字符串`);
+}
+
+function placeholder(value) {
+  return typeof value === "string" && /<[^>]+>/.test(value);
+}
+
+function safeRelativeRef(value, prefix, suffix, field, errors, allowTemplate) {
+  if (allowTemplate && placeholder(value)) return;
+  if (!nonEmpty(value) || path.isAbsolute(value) || value.split("/").includes("..") || !value.startsWith(prefix) || !value.endsWith(suffix)) {
+    errors.push(`${field} 必须是 ${prefix} 下的相对 ${suffix} 文件`);
+  }
+}
+
+async function listPayloadFiles(root, relative = "") {
+  const files = [];
+  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
+    const ref = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) throw new TypeError(`Bundle 不允许符号链接: ${ref}`);
+    if (entry.isDirectory()) files.push(...await listPayloadFiles(root, ref));
+    else if (entry.isFile() && ref !== "visual-baseline.yaml") files.push(ref);
+  }
+  return files.sort();
+}
+
+function validateDigest(value, field, errors, allowTemplate) {
+  if (!(allowTemplate && placeholder(value)) && !SHA256.test(value ?? "")) errors.push(`${field} 必须为 sha256 摘要`);
+}
+
+function canonicalDigestPayload(data) {
+  return {
+    schema_version: data.schema_version,
+    baseline_id: data.baseline_id,
+    feature: data.feature,
+    version: data.version,
+    prototype_ref: data.source?.prototype_ref,
+    prototype_digest: data.source?.prototype_digest,
+    interaction_spec_ref: data.source?.interaction_spec_ref,
+    interaction_spec_digest: data.source?.interaction_spec_digest,
+    state_matrix_ref: data.source?.state_matrix_ref,
+    state_matrix_digest: data.source?.state_matrix_digest,
+    capture_script_ref: data.capture_environment?.capture_script_ref,
+    capture_script_digest: data.capture_environment?.capture_script_digest,
+    capture_result_ref: data.capture_environment?.capture_result_ref,
+    capture_result_digest: data.capture_environment?.capture_result_digest,
+    cases: (data.cases ?? []).map((item) => ({
+      case_id: item.case_id,
+      route: item.route,
+      page: item.page,
+      state: item.state,
+      viewport: item.viewport,
+      theme: item.theme,
+      locale: item.locale,
+      data_scenario: item.data_scenario,
+      image_ref: item.image_ref,
+      image_digest: item.image_digest,
+      image_size_bytes: item.image_size_bytes,
+      mask_ref: item.mask_ref,
+      mask_digest: item.mask_digest,
+      mask_size_bytes: item.mask_size_bytes,
+      semantic_refs: item.semantic_refs,
+      allowed_differences: item.allowed_differences,
+    })),
+  };
+}
+
+export function computeVisualBaselineDigest(data) {
+  return digest(JSON.stringify(canonicalDigestPayload(data)));
+}
+
+function pngDimensions(buffer) {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature) || buffer.toString("ascii", 12, 16) !== "IHDR") {
+    throw new TypeError("文件不是有效 PNG");
+  }
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+export async function validateVisualBaseline(data, { allowTemplate = false, bundleRoot } = {}) {
+  const errors = [];
+  if (!object(data)) return { errors: ["Visual Baseline 必须是对象"] };
+  for (const field of ["schema_version", "baseline_id", "feature", "version", "status", "bundle", "source", "capture_environment", "cases"]) required(data, field, "root", errors);
+  if (data.schema_version !== 1) errors.push("schema_version 必须为 1");
+  requiredString(data, "baseline_id", "root", errors);
+  requiredString(data, "feature", "root", errors);
+  requiredString(data, "version", "root", errors);
+  if (!(allowTemplate && placeholder(data.feature)) && !CASE_ID.test(data.feature ?? "")) errors.push("feature 必须是小写 kebab-case");
+  if (!(allowTemplate && placeholder(data.baseline_id)) && data.baseline_id !== `visual-baseline.${data.feature}`) errors.push("baseline_id 必须为 visual-baseline.<feature>");
+  if (!(allowTemplate && placeholder(data.version)) && !/^v[1-9][0-9]*$/.test(data.version ?? "")) errors.push("version 必须形如 v1");
+  if (!['draft', 'ready-for-human', 'approved', 'stale', 'blocked'].includes(data.status)) errors.push("status 非法");
+
+  const bundle = data.bundle;
+  for (const field of ["format", "root_ref", "digest", "size_bytes", "max_image_bytes", "max_bundle_bytes"]) required(bundle, field, "bundle", errors);
+  if (bundle?.format !== "portable-directory") errors.push("bundle.format 必须为 portable-directory");
+  requiredString(bundle, "root_ref", "bundle", errors);
+  validateDigest(bundle?.digest, "bundle.digest", errors, allowTemplate);
+  if (!(allowTemplate && placeholder(bundle?.size_bytes)) && (!Number.isInteger(bundle?.size_bytes) || bundle.size_bytes < 0 || bundle.size_bytes > MAX_BUNDLE_BYTES)) errors.push("bundle.size_bytes 必须是不超过 100 MiB 的非负整数");
+  if (bundle?.max_image_bytes !== MAX_IMAGE_BYTES) errors.push(`bundle.max_image_bytes 必须为 ${MAX_IMAGE_BYTES}`);
+  if (bundle?.max_bundle_bytes !== MAX_BUNDLE_BYTES) errors.push(`bundle.max_bundle_bytes 必须为 ${MAX_BUNDLE_BYTES}`);
+
+  const source = data.source;
+  for (const field of ["prototype_ref", "prototype_digest", "interaction_spec_ref", "interaction_spec_digest", "state_matrix_ref", "state_matrix_digest"]) requiredString(source, field, "source", errors);
+  for (const field of ["prototype_digest", "interaction_spec_digest", "state_matrix_digest"]) validateDigest(source?.[field], `source.${field}`, errors, allowTemplate);
+  safeRelativeRef(source?.prototype_ref, "sources/", "", "source.prototype_ref", errors, allowTemplate);
+  safeRelativeRef(source?.interaction_spec_ref, "sources/", "", "source.interaction_spec_ref", errors, allowTemplate);
+  safeRelativeRef(source?.state_matrix_ref, "sources/", "", "source.state_matrix_ref", errors, allowTemplate);
+
+  const environment = data.capture_environment;
+  for (const field of ["browser", "browser_version", "operating_system", "fonts_digest", "device_scale_factor", "color_space", "locale", "timezone", "animations_disabled", "cursor_hidden", "capture_script_ref", "capture_script_digest", "capture_result_ref", "capture_result_digest"]) required(environment, field, "capture_environment", errors);
+  if (environment?.browser !== "chromium") errors.push("capture_environment.browser 必须为 chromium");
+  if (environment?.device_scale_factor !== 1) errors.push("capture_environment.device_scale_factor 必须为 1");
+  if (environment?.color_space !== "srgb") errors.push("capture_environment.color_space 必须为 srgb");
+  if (environment?.animations_disabled !== true || environment?.cursor_hidden !== true) errors.push("截图必须关闭动画并隐藏光标");
+  for (const field of ["browser_version", "operating_system", "locale", "timezone"]) requiredString(environment, field, "capture_environment", errors);
+  for (const field of ["fonts_digest", "capture_script_digest", "capture_result_digest"]) validateDigest(environment?.[field], `capture_environment.${field}`, errors, allowTemplate);
+  safeRelativeRef(environment?.capture_script_ref, "capture/", "", "capture_environment.capture_script_ref", errors, allowTemplate);
+  safeRelativeRef(environment?.capture_result_ref, "capture/", "", "capture_environment.capture_result_ref", errors, allowTemplate);
+
+  if (!Array.isArray(data.cases) || data.cases.length === 0) errors.push("cases 必须是非空数组");
+  const ids = new Set();
+  const viewportSizes = new Set();
+  const referencedFiles = new Set();
+  const fileCache = new Map();
+  const readBundleFile = async (ref, field) => {
+    if (!bundleRoot || (allowTemplate && placeholder(ref))) return null;
+    const resolvedRoot = path.resolve(bundleRoot);
+    const filePath = path.resolve(resolvedRoot, ref);
+    if (!filePath.startsWith(`${resolvedRoot}${path.sep}`) || !existsSync(filePath)) {
+      errors.push(`${field} 不可读或越界`);
+      return null;
+    }
+    referencedFiles.add(ref);
+    if (!fileCache.has(ref)) fileCache.set(ref, await readFile(filePath));
+    return fileCache.get(ref);
+  };
+  if (bundleRoot) {
+    for (const [refField, digestField] of [["prototype_ref", "prototype_digest"], ["interaction_spec_ref", "interaction_spec_digest"], ["state_matrix_ref", "state_matrix_digest"]]) {
+      const bytes = await readBundleFile(source?.[refField], `source.${refField}`);
+      if (bytes && digest(bytes) !== source?.[digestField]) errors.push(`source.${digestField} 与文件不一致`);
+    }
+    for (const [refField, digestField] of [["capture_script_ref", "capture_script_digest"], ["capture_result_ref", "capture_result_digest"]]) {
+      const bytes = await readBundleFile(environment?.[refField], `capture_environment.${refField}`);
+      if (bytes && digest(bytes) !== environment?.[digestField]) errors.push(`capture_environment.${digestField} 与文件不一致`);
+    }
+  }
+  for (const [index, item] of (data.cases ?? []).entries()) {
+    const parent = `cases.${index}`;
+    for (const field of ["case_id", "route", "page", "state", "viewport", "theme", "locale", "data_scenario", "image_ref", "image_digest", "image_size_bytes", "mask_ref", "mask_digest", "mask_size_bytes", "semantic_refs", "allowed_differences", "result"]) required(item, field, parent, errors);
+    if (!(allowTemplate && placeholder(item?.case_id)) && !CASE_ID.test(item?.case_id ?? "")) errors.push(`${parent}.case_id 必须是小写 kebab-case`);
+    if (ids.has(item?.case_id)) errors.push(`${parent}.case_id 重复`);
+    ids.add(item?.case_id);
+    for (const field of ["route", "page", "state", "theme", "locale", "data_scenario"]) requiredString(item, field, parent, errors);
+    const viewport = item?.viewport;
+    for (const field of ["name", "width", "height", "scroll_mode", "scroll_position"]) required(viewport, field, `${parent}.viewport`, errors);
+    if (!(allowTemplate && (placeholder(viewport?.width) || placeholder(viewport?.height))) && (!Number.isInteger(viewport?.width) || !Number.isInteger(viewport?.height) || viewport.width <= 0 || viewport.height <= 0)) errors.push(`${parent}.viewport 尺寸必须是正整数`);
+    if (!["viewport", "segment"].includes(viewport?.scroll_mode)) errors.push(`${parent}.viewport.scroll_mode 必须为 viewport/segment`);
+    if (viewport?.scroll_mode === "viewport" && viewport?.scroll_position !== 0) errors.push(`${parent}.viewport.scroll_position 在 viewport 模式必须为 0`);
+    viewportSizes.add(`${viewport?.width}x${viewport?.height}`);
+    safeRelativeRef(item?.image_ref, "images/", ".png", `${parent}.image_ref`, errors, allowTemplate);
+    validateDigest(item?.image_digest, `${parent}.image_digest`, errors, allowTemplate);
+    if (!(allowTemplate && placeholder(item?.image_size_bytes)) && (!Number.isInteger(item?.image_size_bytes) || item.image_size_bytes <= 0 || item.image_size_bytes > MAX_IMAGE_BYTES)) errors.push(`${parent}.image_size_bytes 必须为 1..${MAX_IMAGE_BYTES}`);
+    if (item?.mask_ref === "not-applicable") {
+      if (item?.mask_digest !== "not-applicable" || item?.mask_size_bytes !== 0) errors.push(`${parent} 无 mask 时 digest 必须为 not-applicable 且 size 为 0`);
+    } else {
+      safeRelativeRef(item?.mask_ref, "masks/", ".png", `${parent}.mask_ref`, errors, allowTemplate);
+      validateDigest(item?.mask_digest, `${parent}.mask_digest`, errors, allowTemplate);
+      if (!(allowTemplate && placeholder(item?.mask_size_bytes)) && (!Number.isInteger(item?.mask_size_bytes) || item.mask_size_bytes <= 0 || item.mask_size_bytes > MAX_IMAGE_BYTES)) errors.push(`${parent}.mask_size_bytes 必须为 1..${MAX_IMAGE_BYTES}`);
+    }
+    const allowedSemanticRefs = new Set([source?.prototype_ref, source?.interaction_spec_ref, source?.state_matrix_ref]);
+    if (!Array.isArray(item?.semantic_refs) || item.semantic_refs.length === 0 || item.semantic_refs.some((ref) => !nonEmpty(ref) || !allowedSemanticRefs.has(ref))) errors.push(`${parent}.semantic_refs 必须引用 source 中的可移植快照`);
+    if (!Array.isArray(item?.allowed_differences)) errors.push(`${parent}.allowed_differences 必须是数组`);
+    if (!(allowTemplate && placeholder(item?.result)) && item?.result !== "passed") errors.push(`${parent}.result 必须为 passed`);
+
+    if (bundleRoot && !(allowTemplate && placeholder(item?.image_ref))) {
+      const bytes = await readBundleFile(item.image_ref, `${parent}.image_ref`);
+      if (bytes) {
+        try {
+          const dimensions = pngDimensions(bytes);
+          if (dimensions.width !== viewport.width || dimensions.height !== viewport.height) errors.push(`${parent}.image_ref PNG 尺寸与 viewport 不一致`);
+        } catch (error) { errors.push(`${parent}.image_ref ${error.message}`); }
+        if (digest(bytes) !== item.image_digest) errors.push(`${parent}.image_digest 与文件不一致`);
+        if (bytes.length !== item.image_size_bytes) errors.push(`${parent}.image_size_bytes 与文件不一致`);
+      }
+      if (item?.mask_ref !== "not-applicable") {
+        const mask = await readBundleFile(item.mask_ref, `${parent}.mask_ref`);
+        if (mask) {
+          try {
+            const dimensions = pngDimensions(mask);
+            if (dimensions.width !== viewport.width || dimensions.height !== viewport.height) errors.push(`${parent}.mask_ref PNG 尺寸与 viewport 不一致`);
+          } catch (error) { errors.push(`${parent}.mask_ref ${error.message}`); }
+          if (digest(mask) !== item.mask_digest) errors.push(`${parent}.mask_digest 与文件不一致`);
+          if (mask.length !== item.mask_size_bytes) errors.push(`${parent}.mask_size_bytes 与文件不一致`);
+        }
+      }
+    }
+  }
+  if (!allowTemplate && (!viewportSizes.has("1440x900") || !viewportSizes.has("390x844"))) errors.push("Visual Baseline 至少覆盖 1440x900 与 390x844");
+  if (!allowTemplate && data.status !== "approved") errors.push("正式 Visual Baseline 必须达到 approved");
+  if (!allowTemplate && computeVisualBaselineDigest(data) !== bundle?.digest) errors.push("bundle.digest 与 manifest 内容不一致");
+  if (bundleRoot) {
+    let payloadFiles = [];
+    try { payloadFiles = await listPayloadFiles(path.resolve(bundleRoot)); } catch (error) { errors.push(error.message); }
+    for (const ref of payloadFiles) if (!referencedFiles.has(ref)) errors.push(`Bundle 包含未登记 payload: ${ref}`);
+    const actualBundleBytes = [...fileCache.values()].reduce((sum, bytes) => sum + bytes.length, 0);
+    if (actualBundleBytes !== bundle?.size_bytes) errors.push("bundle.size_bytes 与全部已登记 payload 大小不一致");
+  }
+  return { errors };
+}
+
+async function loadYaml(file) {
+  const document = parseDocument(await readFile(file, "utf8"), { uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+export async function sealVisualBaseline(file, bundleRoot) {
+  const data = await loadYaml(file);
+  const referencedFiles = new Set();
+  const payloads = new Map();
+  const consume = async (ref) => {
+    if (!nonEmpty(ref) || path.isAbsolute(ref) || ref.split("/").includes("..")) throw new TypeError(`Bundle 引用越界: ${ref}`);
+    referencedFiles.add(ref);
+    if (!payloads.has(ref)) payloads.set(ref, await readFile(path.resolve(bundleRoot, ref)));
+    return payloads.get(ref);
+  };
+  for (const [refField, digestField] of [["prototype_ref", "prototype_digest"], ["interaction_spec_ref", "interaction_spec_digest"], ["state_matrix_ref", "state_matrix_digest"]]) {
+    data.source[digestField] = digest(await consume(data.source[refField]));
+  }
+  for (const [refField, digestField] of [["capture_script_ref", "capture_script_digest"], ["capture_result_ref", "capture_result_digest"]]) {
+    data.capture_environment[digestField] = digest(await consume(data.capture_environment[refField]));
+  }
+  for (const item of data.cases ?? []) {
+    const bytes = await consume(item.image_ref);
+    const dimensions = pngDimensions(bytes);
+    if (dimensions.width !== item.viewport.width || dimensions.height !== item.viewport.height) throw new TypeError(`${item.case_id} PNG 尺寸与 viewport 不一致`);
+    if (bytes.length > MAX_IMAGE_BYTES) throw new TypeError(`${item.case_id} PNG 超过 5 MiB`);
+    item.image_digest = digest(bytes);
+    item.image_size_bytes = bytes.length;
+    item.result = "passed";
+    if (item.mask_ref === "not-applicable") {
+      item.mask_digest = "not-applicable";
+      item.mask_size_bytes = 0;
+    } else {
+      const mask = await consume(item.mask_ref);
+      const maskDimensions = pngDimensions(mask);
+      if (maskDimensions.width !== item.viewport.width || maskDimensions.height !== item.viewport.height) throw new TypeError(`${item.case_id} mask PNG 尺寸与 viewport 不一致`);
+      if (mask.length > MAX_IMAGE_BYTES) throw new TypeError(`${item.case_id} mask PNG 超过 5 MiB`);
+      item.mask_digest = digest(mask);
+      item.mask_size_bytes = mask.length;
+    }
+  }
+  const payloadFiles = await listPayloadFiles(path.resolve(bundleRoot));
+  for (const ref of payloadFiles) if (!referencedFiles.has(ref)) throw new TypeError(`Bundle 包含未登记 payload: ${ref}`);
+  const sizeBytes = [...payloads.values()].reduce((sum, bytes) => sum + bytes.length, 0);
+  if (sizeBytes > MAX_BUNDLE_BYTES) throw new TypeError("Visual Baseline Bundle 超过 100 MiB");
+  data.bundle.size_bytes = sizeBytes;
+  data.bundle.digest = computeVisualBaselineDigest(data);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, stringify(data));
+  return data;
+}
+
+function args(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) { result._.push(item); continue; }
+    const key = item.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) result[key] = true;
+    else { result[key] = value; index += 1; }
+  }
+  return result;
+}
+
+async function main(argv) {
+  const parsed = args(argv);
+  const [command, file] = parsed._;
+  if (!file || !["validate", "seal"].includes(command)) throw new TypeError("usage: visual-baseline-contract.mjs validate|seal <visual-baseline.yaml> [--bundle-root <dir>] [--allow-template]");
+  const bundleRoot = parsed["bundle-root"] ? path.resolve(parsed["bundle-root"]) : undefined;
+  if (command === "seal") {
+    if (!bundleRoot) throw new TypeError("seal 必须提供 --bundle-root");
+    await sealVisualBaseline(path.resolve(file), bundleRoot);
+  }
+  const data = await loadYaml(path.resolve(file));
+  const result = await validateVisualBaseline(data, { allowTemplate: Boolean(parsed["allow-template"]), bundleRoot });
+  if (result.errors.length) throw new TypeError(result.errors.join("\n"));
+  process.stdout.write(`Visual Baseline ${command} passed\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) main(process.argv.slice(2)).catch((error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });

package/template/.codex/skills/yss-prototype-stage/tests/run-scenarios.mjs

@@ -1,37 +1,54 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
+import { buildDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
 import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { prepareFlowPrototype, prepareStaticPrototype, validatePrototypeEvidence, validatePrototypeProject } from "../scripts/prototype-contract.mjs";
+import { prepareFlowPrototype, prepareStaticPrototype, validatePrototypeEvidence, validatePrototypeProject, prototypeDecisionSnapshot } from "../scripts/prototype-contract.mjs";
+import { sealVisualBaseline, validateVisualBaseline } from "../scripts/visual-baseline-contract.mjs";
 
 const tempRoot = await mkdtemp(path.join(os.tmpdir(), "yss-prototype-contract-"));
 const projectRoot = path.join(tempRoot, "project");
 const feature = "order-review";
 await mkdir(path.join(projectRoot, "docs/design/tokens"), { recursive: true });
+await writeFile(path.join(projectRoot, "DESIGN.md"), "---\nversion: alpha\n---\n");
 await writeFile(path.join(projectRoot, "docs/design/tokens/theme.json"), JSON.stringify({ token: { colorPrimary: "#3371ff", borderRadius: 6, controlHeight: 32 } }, null, 2));
 
 const h1Root = path.join(projectRoot, "docs/.scratch", feature, "design/prototypes");
 await prepareStaticPrototype({ projectRoot, root: h1Root, feature });
 assert.match(await readFile(path.join(h1Root, "index.html"), "utf8"), /H1 · visual-review/);
+const h1Styles = await readFile(path.join(h1Root, "styles.css"), "utf8");
+for (const token of ["--brand-font-family", "--brand-color-text", "--brand-color-bg-layout", "--brand-color-bg-container", "--yss-color-primary-control", "--yss-control-height-compact", "--brand-size-lg", "--brand-size", "--brand-size-sm", "--brand-border-radius-lg", "--brand-border-radius"]) assert.match(h1Styles, new RegExp(token));
+for (const staleAlias of ["--font-family", "--layout-background", "--container-background", "--brand-primary"]) assert.doesNotMatch(h1Styles, new RegExp(staleAlias));
+for (const hardcodedDeclaration of ["padding:24px", "padding:20px", "min-height:32px", "border-radius:8px", "border-radius:6px"]) assert.doesNotMatch(h1Styles, new RegExp(hardcodedDeclaration));
 assert.deepEqual((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors, []);
 await writeFile(path.join(h1Root, "package.json"), "{}\n");
 assert((await validatePrototypeProject({ root: h1Root, profile: "H1" })).errors.some((message) => message.includes("package.json")), "H1 必须拒绝伪构建依赖");
 
 const h2Feature = "approval-flow";
 const h2Root = path.join(projectRoot, "docs/.scratch", h2Feature, "design/prototypes");
-await mkdir(path.join(h2Root, "src"), { recursive: true });
-await writeFile(path.join(h2Root, "index.html"), "<!doctype html><div id=app></div>\n");
-await writeFile(path.join(h2Root, "package.json"), JSON.stringify({ name: "approval-flow-prototype", private: true, type: "module", scripts: { build: "vite build" }, dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" } }, null, 2));
-await prepareFlowPrototype({ projectRoot, root: h2Root, feature: h2Feature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
+const h2Manifest = await prepareFlowPrototype({ projectRoot, root: h2Root, feature: h2Feature, pnpmVersion: "10.15.0" });
 await writeFile(path.join(h2Root, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
-await writeFile(path.join(h2Root, "src/App.jsx"), 'import { ConfigProvider } from "antd"; import { yssTheme } from "./yss-theme.js"; export function App(){return <ConfigProvider theme={yssTheme}/>;}\n');
-assert.deepEqual((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.2" })).errors, []);
-assert((await validatePrototypeProject({ root: h2Root, profile: "H2", targetAntdVersion: "6.6.1" })).errors.some((message) => message.includes("精确锁定")));
+assert.equal(h2Manifest.component_basis, "vue-antdv-next");
+assert.equal(h2Manifest.library.version, "1.5.2");
+assert.match(await readFile(path.join(h2Root, "src/App.vue"), "utf8"), /a-config-provider/);
+assert.match(await readFile(path.join(h2Root, "src/yss-theme.js"), "utf8"), /compactAlgorithm/);
+assert.deepEqual((await validatePrototypeProject({ root: h2Root, profile: "H2" })).errors, []);
+assert((await validatePrototypeProject({ root: h2Root, profile: "H2", componentBasis: "vue-antdv-next", libraryVersion: "1.5.1" })).errors.some((message) => message.includes("精确锁定")));
+
+const reactFeature = "legacy-react-flow";
+const reactRoot = path.join(projectRoot, "docs/.scratch", reactFeature, "design/prototypes");
+await mkdir(path.join(reactRoot, "src"), { recursive: true });
+await writeFile(path.join(reactRoot, "index.html"), "<!doctype html><div id=app></div>\n");
+await writeFile(path.join(reactRoot, "package.json"), JSON.stringify({ name: "legacy-react-flow-prototype", private: true, type: "module", scripts: { build: "vite build" }, dependencies: { react: "19.2.0", "react-dom": "19.2.0", vite: "6.4.2" } }, null, 2));
+await prepareFlowPrototype({ projectRoot, root: reactRoot, feature: reactFeature, targetAntdVersion: "6.6.2", pnpmVersion: "10.15.0" });
+await writeFile(path.join(reactRoot, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\n");
+await writeFile(path.join(reactRoot, "src/App.jsx"), 'import { ConfigProvider } from "antd"; import { yssTheme } from "./yss-theme.js"; export function App(){return <ConfigProvider theme={yssTheme}/>;}\n');
+assert.deepEqual((await validatePrototypeProject({ root: reactRoot, profile: "H2", targetAntdVersion: "6.6.2" })).errors, []);
 
 function common(profile, kind, block) {
-  return {
-    schema_version: 3,
+  const data = {
+    schema_version: 4,
     feature,
     prototype_ref: `docs/.scratch/${feature}/design/prototypes/index.html`,
     prototype_profile: profile,
@@ -45,12 +62,13 @@ function common(profile, kind, block) {
     },
     upstream_refs: { spec_ref: "spec.md", interaction_spec_ref: "interaction.md", low_fidelity_ref: "low.md", state_matrix_ref: "states.md", prototype_review_ref: "review.md" },
     source_visual: { ideation_status: "not-applicable", selected_ref: "approved-pattern.md", reuse_reason: "复用已批准模式" },
-    design_baseline: { project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
+    design_baseline: { canonical_design_ref: "DESIGN.md", canonical_design_digest: "sha256:design", project_design_ref: "docs/design/design.md", project_token_refs: ["docs/design/tokens/theme.json"], project_token_baseline_digest: "sha256:tokens", project_override_reviewed: true },
+    visual_baseline: { manifest_ref: `docs/.scratch/${feature}/handoff/visual-baseline-v1/visual-baseline.yaml`, baseline_id: `visual-baseline.${feature}`, version: "v1", digest: `sha256:${"a".repeat(64)}`, status: "approved", case_ids: ["primary-desktop", "primary-narrow"] },
     browser_delivery: {
       delivery_kind: "static-directory", entry_ref: `docs/.scratch/${feature}/design/prototypes/index.html`, rendered_nonblank: true, prototype_digest: "sha256:prototype",
       viewports: [
-        { name: "desktop", size: "1440x900", result: "passed", screenshot_ref: "desktop.png" },
-        { name: "narrow", size: "390x844", result: "passed", screenshot_ref: "narrow.png" }
+        { name: "desktop", size: "1440x900", result: "passed", case_ids: ["primary-desktop"] },
+        { name: "narrow", size: "390x844", result: "passed", case_ids: ["primary-narrow"] }
       ],
       console_result: "passed", console_ref: "console.txt"
     },
@@ -65,6 +83,10 @@ function common(profile, kind, block) {
     user_confirmation: { result: "approved", confirmation_ref: "confirmation.md", confirmed_decision: "接受当前设计", operable_scope: ["主操作"], simulations_or_gaps: [] },
     gaps: [], blockers: []
   };
+  const f = buildDecisionFixture(path.join(tempRoot, `decision-${profile}-${kind}`), { boundary: "gate.user-confirmation", scope: data.user_confirmation.operable_scope, subjectContent: JSON.stringify(prototypeDecisionSnapshot(data)) });
+  data.user_confirmation.user_decision_ref = f.ref;
+  data.user_confirmation.decision_subject_ref = f.requirement.subject_ref;
+  return data;
 }
 
 const h1Evidence = common("H1", "visual-review", { visual_review: {
@@ -73,20 +95,31 @@ const h1Evidence = common("H1", "visual-review", { visual_review: {
   reduced_motion: { applicable: false, result: "not-applicable", evidence_ref: "not-applicable" }
 } });
 assert.deepEqual(validatePrototypeEvidence(h1Evidence).errors, []);
+const missingCanonicalDesign = structuredClone(h1Evidence);
+delete missingCanonicalDesign.design_baseline.canonical_design_ref;
+delete missingCanonicalDesign.design_baseline.canonical_design_digest;
+assert(validatePrototypeEvidence(missingCanonicalDesign).errors.some((message) => message.includes("canonical_design")), "schema v4 必须绑定根 DESIGN.md 及其 digest");
 const fakeH1 = structuredClone(h1Evidence);
 fakeH1.profile_evidence.visual_review.lockfile_ref = "pnpm-lock.yaml";
 assert(validatePrototypeEvidence(fakeH1).errors.some((message) => message.includes("H1 禁止字段")));
 
 const h2Evidence = common("H2", "flow-review", { flow_review: {
-  implementation: { framework: "react", runtime_build_required: true, package_manager: "pnpm", package_manifest_ref: "package.json", lockfile_ref: "pnpm-lock.yaml", build_command: "pnpm build", build_result: "passed" },
+  implementation: { framework: "vue", runtime_build_required: true, package_manager: "pnpm", package_manifest_ref: "package.json", lockfile_ref: "pnpm-lock.yaml", build_command: "pnpm build", build_result: "passed" },
   main_flow_result: "passed", exceptional_state_result: "passed", exceptional_state_ref: "conflict.png", keyboard_result: "passed", focus_result: "passed", contrast_result: "passed", zoom_200_result: "passed", reduced_motion_result: "passed",
   visual_regression: { applicable: true, result: "passed", evidence_ref: "visual.json" },
-  prototype_library_facts: { applicable: true, component_basis: "react-antd-6", source: "fact-pack", actual_antd_version: "6.6.2", manifest_ref: "docs/design/facts/antd/6.6.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false }
+  prototype_library_facts: { applicable: true, component_basis: "vue-antdv-next", source: "fact-pack", library_package: "antdv-next", library_version: "1.5.2", manifest_ref: "docs/design/facts/antdv-next/1.5.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], canonical_design_digest: "sha256:design", project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false }
 } });
 assert.deepEqual(validatePrototypeEvidence(h2Evidence).errors, []);
+const legacyReactEvidence = structuredClone(h2Evidence);
+legacyReactEvidence.profile_evidence.flow_review.implementation.framework = "react";
+legacyReactEvidence.profile_evidence.flow_review.prototype_library_facts = { applicable: true, component_basis: "react-antd-6", source: "fact-pack", actual_antd_version: "6.6.2", manifest_ref: "docs/design/facts/antd/6.6.2/manifest.json", manifest_digest: "sha256:facts", components_covered: ["Button"], canonical_design_digest: "sha256:design", project_token_baseline_digest: "sha256:tokens", new_api_uncertainty: false };
+assert.deepEqual(validatePrototypeEvidence(legacyReactEvidence).errors, []);
 const staleFacts = structuredClone(h2Evidence);
 staleFacts.profile_evidence.flow_review.prototype_library_facts.project_token_baseline_digest = "sha256:old";
 assert(validatePrototypeEvidence(staleFacts).errors.some((message) => message.includes("Token digest")));
+const staleCanonicalDesign = structuredClone(h2Evidence);
+staleCanonicalDesign.profile_evidence.flow_review.prototype_library_facts.canonical_design_digest = "sha256:old-design";
+assert(validatePrototypeEvidence(staleCanonicalDesign).errors.some((message) => message.includes("DESIGN.md digest")));
 const fakeH3Claim = structuredClone(h2Evidence);
 fakeH3Claim.profile_evidence.flow_review.real_component_verified = true;
 assert(validatePrototypeEvidence(fakeH3Claim).errors.some((message) => message.includes("禁止生产组件字段")));
@@ -101,7 +134,53 @@ const invalidHandoff = structuredClone(h2Evidence);
 invalidHandoff.implementation_handoff.verification_targets[0].target_stage = "prototype";
 assert(validatePrototypeEvidence(invalidHandoff).errors.some((message) => message.includes("前端实现阶段")));
 
-assert(validatePrototypeEvidence({ schema_version: 2 }).errors.some((message) => message.includes("只读旧证据")));
-assert.deepEqual(validatePrototypeEvidence({ schema_version: 2 }, { allowLegacy: true }).errors, []);
+assert(validatePrototypeEvidence({ schema_version: 3 }).errors.some((message) => message.includes("只读旧证据")));
+assert.deepEqual(validatePrototypeEvidence({ schema_version: 3 }, { allowLegacy: true }).errors, []);
+
+function pngHeader(width, height) {
+  const value = Buffer.alloc(24);
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(value, 0);
+  value.writeUInt32BE(13, 8); value.write("IHDR", 12, "ascii"); value.writeUInt32BE(width, 16); value.writeUInt32BE(height, 20);
+  return value;
+}
+const bundleRoot = path.join(projectRoot, "docs/.scratch", feature, "handoff/visual-baseline-v1");
+await mkdir(path.join(bundleRoot, "images"), { recursive: true });
+await mkdir(path.join(bundleRoot, "sources"), { recursive: true });
+await mkdir(path.join(bundleRoot, "capture"), { recursive: true });
+await writeFile(path.join(bundleRoot, "images/primary-desktop.png"), pngHeader(1440, 900));
+await writeFile(path.join(bundleRoot, "images/primary-narrow.png"), pngHeader(390, 844));
+await writeFile(path.join(bundleRoot, "sources/prototype.snapshot.html"), "<!doctype html><main>order review</main>\n");
+await writeFile(path.join(bundleRoot, "sources/interaction-spec.snapshot.md"), "# Interaction\n");
+await writeFile(path.join(bundleRoot, "sources/state-matrix.snapshot.md"), "# States\n");
+await writeFile(path.join(bundleRoot, "capture/capture.mjs"), "// deterministic capture\n");
+await writeFile(path.join(bundleRoot, "capture/result.json"), "{\"result\":\"passed\"}\n");
+const baselineFile = path.join(bundleRoot, "visual-baseline.yaml");
+const baseline = {
+  schema_version: 1, baseline_id: `visual-baseline.${feature}`, feature, version: "v1", status: "approved",
+  bundle: { format: "portable-directory", root_ref: `docs/.scratch/${feature}/handoff/visual-baseline-v1`, digest: `sha256:${"0".repeat(64)}`, size_bytes: 0, max_image_bytes: 5242880, max_bundle_bytes: 104857600 },
+  source: { prototype_ref: "sources/prototype.snapshot.html", prototype_digest: `sha256:${"1".repeat(64)}`, interaction_spec_ref: "sources/interaction-spec.snapshot.md", interaction_spec_digest: `sha256:${"2".repeat(64)}`, state_matrix_ref: "sources/state-matrix.snapshot.md", state_matrix_digest: `sha256:${"3".repeat(64)}` },
+  capture_environment: { browser: "chromium", browser_version: "140.0.0", operating_system: "linux", fonts_digest: `sha256:${"4".repeat(64)}`, device_scale_factor: 1, color_space: "srgb", locale: "zh-CN", timezone: "Asia/Shanghai", animations_disabled: true, cursor_hidden: true, capture_script_ref: "capture/capture.mjs", capture_script_digest: `sha256:${"5".repeat(64)}`, capture_result_ref: "capture/result.json", capture_result_digest: `sha256:${"6".repeat(64)}` },
+  cases: [
+    { case_id: "primary-desktop", route: "/orders", page: "OrderPage", state: "normal", viewport: { name: "desktop", width: 1440, height: 900, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-desktop.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/prototype.snapshot.html", "sources/interaction-spec.snapshot.md"], allowed_differences: [], result: "passed" },
+    { case_id: "primary-narrow", route: "/orders", page: "OrderPage", state: "normal", viewport: { name: "narrow", width: 390, height: 844, scroll_mode: "viewport", scroll_position: 0 }, theme: "compact-light", locale: "zh-CN", data_scenario: "primary", image_ref: "images/primary-narrow.png", image_digest: `sha256:${"0".repeat(64)}`, image_size_bytes: 1, mask_ref: "not-applicable", mask_digest: "not-applicable", mask_size_bytes: 0, semantic_refs: ["sources/state-matrix.snapshot.md"], allowed_differences: [], result: "passed" }
+  ]
+};
+await writeFile(baselineFile, JSON.stringify(baseline, null, 2));
+const sealed = await sealVisualBaseline(baselineFile, bundleRoot);
+assert.deepEqual((await validateVisualBaseline(sealed, { bundleRoot })).errors, []);
+const tamperedDigest = structuredClone(sealed);
+tamperedDigest.cases[0].image_digest = `sha256:${"f".repeat(64)}`;
+assert((await validateVisualBaseline(tamperedDigest, { bundleRoot })).errors.some((message) => message.includes("image_digest 与文件不一致")));
+const missingNarrow = structuredClone(sealed);
+missingNarrow.cases = missingNarrow.cases.slice(0, 1);
+assert((await validateVisualBaseline(missingNarrow)).errors.some((message) => message.includes("390x844")));
+const badDpr = structuredClone(sealed);
+badDpr.capture_environment.device_scale_factor = 2;
+assert((await validateVisualBaseline(badDpr)).errors.some((message) => message.includes("device_scale_factor")));
+const traversal = structuredClone(sealed);
+traversal.source.prototype_ref = "../prototype.html";
+assert((await validateVisualBaseline(traversal)).errors.some((message) => message.includes("source.prototype_ref")));
+await writeFile(path.join(bundleRoot, "capture/unregistered.log"), "unexpected\n");
+assert((await validateVisualBaseline(sealed, { bundleRoot })).errors.some((message) => message.includes("未登记 payload")));
 
 process.stdout.write("YSS prototype profile contract scenarios passed\n");

package/template/.codex/skills/yss-repository/SKILL.md

@@ -5,6 +5,12 @@ description: Use when generating or refactoring YSS Infrastructure persistence m
 
 # yss-repository
 
+## 架构分流（先执行）
+
+读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。支持的分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+
+以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+
 这是一个偏代码生成和结构补全的 skill，适合在已有工程里补 Repository 层，不适合替代完整脚手架。
 
 ## 何时使用

package/template/.codex/skills/yss-repository/references/profiles/layered-mvc-service.md

@@ -0,0 +1,3 @@
+# layered-mvc-service
+
+先读仓库 `docs/agents/backend-architecture-profiles.md`。依据批准的数据合同写入 repository 的 po/repository/convertor 及 Mapper XML；无需领域模型或 Gateway。使用 `yss-mybatis` 的 MyBatis-Plus 体系；保留 cause，避免向上暴露原始 SQL/凭据。事务由 service 用例拥有。测试覆盖查询、分页、回滚与字段转换；H2 不证明生产方言。生产驱动/数据源接入须另有批准的存储工作单元。

package/template/.codex/skills/yss-repository/references/profiles/mvc-data-analysis-v1.md

@@ -0,0 +1,3 @@
+# mvc-data-analysis-v1
+
+遵守 `layered-mvc-service.md`，但事务所有者为 `core`。repository 不依赖 core/client/server，不生成 DDD Gateway。数据分析的动态排序、分组、过滤均须白名单及参数绑定；只消费批准的数据和查询合同。

package/template/.codex/skills/yss-repository/references/profiles/target-domain-model.md

@@ -0,0 +1,3 @@
+# target-domain-model
+
+完整执行规则见 `../infrastructure-layer-guide.md`。Domain Gateway 和 Application Query Port 必须已存在；本 Skill 只在 Infrastructure 实现，不反向创建领域端口。事务归 Application。

package/template/.codex/skills/yss-skill-source-index-refresh/references/source-map-config.md

@@ -25,6 +25,5 @@ Frontend docs are written to these skills:
 | `yss-ui` | components, hooks, skills docs |
 | `yss-components` | components docs |
 | `yss-hook` | hooks docs |
-| `yss-page-module-development` | components and hooks docs |
 | `yss-use-table-height` | hooks docs |
 | `yss-use-tree-height` | hooks docs |

package/template/.codex/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs

@@ -6,7 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
-const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
+const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-ui-business-page-generation":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
 const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
 const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
 const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);