@entrorove/skill 0.1.62 → 0.1.67

package/design-frameworks.mjs

@@ -0,0 +1,4 @@
+export const FRAMEWORK_DOC_HOSTS = Object.freeze({ react: ['react.dev'], 'react-dom': ['react.dev'], vue: ['vuejs.org'], svelte: ['svelte.dev'],
+  next: ['nextjs.org'], nuxt: ['nuxt.com'], '@angular/core': ['angular.dev'], 'element-plus': ['element-plus.org'],
+  antd: ['ant.design'], '@ant-design/icons': ['ant.design'], bootstrap: ['getbootstrap.com'],
+  tailwindcss: ['tailwindcss.com'], '@mui/material': ['mui.com'], '@dcloudio/uni-app': ['uniapp.dcloud.net.cn'] });

package/design-gate.mjs

@@ -0,0 +1,19 @@
+import { designFail, validateDesignPolicy } from './design-policy.mjs';
+import { designUiCandidate, assertDesignLint } from './design-lint.mjs';
+import { assertDesignArtifacts, designOriginalSource } from './design-store.mjs';
+import { assertFrozenDesignFrameworks } from './design-research.mjs';
+
+import { assertDesignDeclaration } from './design-declaration.mjs';
+export { assertDesignDeclaration } from './design-declaration.mjs';
+export async function assertDesignWrite(input, pass, name, before = '', after = '') {
+  const policy = pass.disciplinePolicy;
+  if (!designUiCandidate(name, before, after) && !policy?.design?.rules.uiPaths.includes(name)) return null;
+  assertDesignDeclaration(policy, [name]);
+  const design = validateDesignPolicy(policy?.design);
+  if (design.flowId !== pass.flowId || design.flowId !== input.flowId || !policy.approval && !policy.designApproval
+    || !design.rules.uiPaths.includes(name)) designFail('APPROVAL_REQUIRED', 'This UI path needs the exact original account-bound design confirmation in its signed write pass');
+  await assertDesignArtifacts(design, input);
+  await assertFrozenDesignFrameworks(input, design);
+  assertDesignLint(design, name, before, after, await designOriginalSource(design, name));
+  return { baselineDigest: design.baselineDigest, lint: 'passed' };
+}

package/design-lint.mjs

@@ -0,0 +1,115 @@
+import ts from 'typescript';
+import postcss from 'postcss';
+import { parse as parseVue } from '@vue/compiler-sfc';
+import { designFail, validateDesignPolicy } from './design-policy.mjs';
+import { designUiAsset } from './design-ui.mjs';
+
+export { designUiCandidate } from './design-ui.mjs';
+const issue = (rule, detail) => ({ rule, detail });
+function styleIssues(source, name, rules) {
+  let tree; try { tree = postcss.parse(source, { from: name }); }
+  catch { return [issue('css-parse', 'Use supported CSS; uncompiled preprocessors require a separately reviewed compiled CSS source')]; }
+  const found = [];
+  tree.walkAtRules(rule => { if (['import', 'tailwind', 'apply'].includes(rule.name)) found.push(issue('style-indirection', rule.toString())); });
+  tree.walkDecls(declaration => {
+    const { prop, value } = declaration;
+    if (declaration.important) found.push(issue('important', declaration.toString()));
+    if (prop.startsWith('--')) {
+      if (name !== rules.tokenPath || rules.tokens[prop] !== value) found.push(issue('unapproved-token', declaration.toString()));
+    } else if (/^(?:color|background(?:-color)?|font(?:-size|-family|-weight)?|padding.*|margin.*|gap|.*-gap|border(?:-color|-radius)?|box-shadow)$/.test(prop)
+      && !/^(?:0|none|inherit|initial|unset|transparent|currentColor|auto)$/.test(value)
+      && !/^var\(--[a-z0-9-]+\)$/.test(value)) found.push(issue('design-token-required', declaration.toString()));
+    for (const [, token] of value.matchAll(/var\((--[a-z0-9-]+)/g)) if (!Object.hasOwn(rules.tokens, token)) found.push(issue('unknown-token', token));
+  });
+  return found;
+}
+function markupIssues(markup, rules, imports) {
+  const found = [];
+  for (const match of markup.matchAll(/<([A-Za-z][\w.-]*)([^<>]*?)\/?\s*>/g)) {
+    const [, tag, attributes] = match;
+    if (/\b(?:style|v-html|dangerouslySetInnerHTML)\s*=|\{\s*\.\.\./.test(attributes)) found.push(issue('unsafe-markup-projection', match[0]));
+    const replacement = rules.replacements.find(item => item.native === tag.toLowerCase());
+    if (replacement && tag !== replacement.component) found.push(issue('framework-component-required', match[0]));
+    if (tag[0] === tag[0].toLowerCase()) {
+      if (!rules.nativeTags.includes(tag)) found.push(issue('unapproved-native', tag));
+    } else if (!imports.has(tag) && !rules.componentModules.some(module => module.exports.includes(tag))) found.push(issue('unapproved-component', tag));
+  }
+  return found;
+}
+function scriptIssues(source, name, rules) {
+  const tree = ts.createSourceFile(name.replace(/\.[^.]+$/, '.tsx'), source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  if (tree.parseDiagnostics.length) return { found: [issue('script-parse', 'Unsupported UI source syntax')], imports: new Set() };
+  const found = [], imports = new Set();
+  const walk = node => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      const module = node.moduleSpecifier.text, approved = rules.componentModules.find(item => item.module === module);
+      const bindings = node.importClause?.namedBindings;
+      if (approved && bindings && ts.isNamedImports(bindings)) for (const element of bindings.elements) {
+        const exported = (element.propertyName ?? element.name).text;
+        if (!approved.exports.includes(exported)) found.push(issue('unapproved-component-import', node.getText(tree)));
+        else imports.add(element.name.text);
+      }
+      if (/\.(?:css|scss|less|sass|styl)$/.test(module) && !rules.frameworkStyleImports?.includes(module)
+        && !rules.stylePaths.some(file => module.endsWith(file) || file.endsWith(module.replace(/^\.\//, '')))) found.push(issue('unapproved-style-import', node.getText(tree)));
+      if (!module.startsWith('.') && !approved && !rules.frameworkStyleImports?.includes(module)
+        && !['react', 'react-dom', 'react-dom/client', 'vue', 'svelte', 'svelte/store', 'next/link', 'next/image'].includes(module)) found.push(issue('unapproved-ui-import', node.getText(tree)));
+    }
+    if (ts.isJsxSpreadAttribute(node) || ts.isJsxAttribute(node) && ['style', 'dangerouslySetInnerHTML'].includes(node.name.getText(tree))) found.push(issue('unsafe-markup-projection', node.getText(tree)));
+    if (ts.isPropertyAccessExpression(node) && ['innerHTML', 'outerHTML', 'style', 'insertAdjacentHTML', 'createElement'].includes(node.name.text)) found.push(issue('dynamic-ui-bypass', node.getText(tree)));
+    if (ts.isIdentifier(node) && ['eval', 'Function', 'styled'].includes(node.text) || ts.isCallExpression(node)
+      && /^(?:Object\.(?:entries|values|keys)|JSON\.stringify)$/.test(node.expression.getText(tree))
+      && (!ts.isObjectLiteralExpression(node.arguments[0] ?? tree)
+        || node.arguments[0].properties.some(property => ts.isSpreadAssignment(property) || ts.isComputedPropertyName(property.name)))) found.push(issue('unbounded-ui-projection', node.getText(tree)));
+    ts.forEachChild(node, walk);
+  };
+  walk(tree);
+  return { found, imports };
+}
+export function designLint(name, source, rules) {
+  if (designUiAsset(name)) return [];
+  if (typeof source !== 'string' || Buffer.byteLength(source) > 2_097_152) designFail('LINT_LIMIT', 'UI lint requires bounded UTF-8 source');
+  if (/\.(?:scss|sass|less|styl|wxml|wxss|axml|acss)$/i.test(name)) return [issue('unsupported-ui-language', name)];
+  if (/\.css$/i.test(name)) return styleIssues(source, name, rules);
+  let markup = source, script = source, styles = [];
+  if (/\.vue$/i.test(name)) {
+    const { descriptor, errors } = parseVue(source);
+    if (errors.length) return [issue('vue-parse', name)];
+    markup = descriptor.template?.content ?? ''; script = [descriptor.script?.content, descriptor.scriptSetup?.content].filter(Boolean).join('\n');
+    styles = descriptor.styles;
+  } else if (/\.(?:html?|svelte)$/i.test(name)) {
+    script = [...source.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/g)].map(match => match[1]).join('\n');
+    styles = [...source.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)].map(match => ({ content: match[1] }));
+    markup = source.replace(/<(?:script|style)\b[^>]*>[\s\S]*?<\/(?:script|style)>/g, '');
+  }
+  const parsed = scriptIssues(script, name, rules), found = [...parsed.found, ...markupIssues(markup, rules, parsed.imports)];
+  if (styles.length) found.push(issue('central-style-source-required', name));
+  return found;
+}
+export function assertDesignLint(policy, name, before, after, approvedBefore = before) {
+  validateDesignPolicy(policy);
+  const retained = new Map();
+  const inspect = source => [...designLint(name, source, policy.rules), ...privateFieldIssues(source, name, policy)];
+  const approved = new Map();
+  for (const problem of inspect(approvedBefore)) { const key = JSON.stringify(problem); approved.set(key, (approved.get(key) ?? 0) + 1); }
+  for (const problem of inspect(before)) { const key = JSON.stringify(problem); retained.set(key, Math.min((retained.get(key) ?? 0) + 1, approved.get(key) ?? 0)); }
+  const introduced = inspect(after).filter(problem => {
+    const key = JSON.stringify(problem), count = retained.get(key) ?? 0;
+    if (count) { retained.set(key, count - 1); return false; } return true;
+  });
+  if (introduced.length) designFail('LINT', `UI write refused: ${introduced.map(item => item.rule).join(', ')}. Follow the approved framework, component, token and field projection rules`);
+  return { introduced: 0 };
+}
+function privateFieldIssues(source, name, policy) {
+  if (designUiAsset(name)) return [];
+  const fields = new Set(policy.site.pages.flatMap(page => page.internalFields)), found = [];
+  if (!fields.size) return found;
+  const tree = ts.createSourceFile(name, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const walk = node => {
+    const field = ts.isPropertyAccessExpression(node) ? node.name.text
+      : ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text
+        : (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) ? node.name.text : null;
+    if (fields.has(field)) found.push(issue('private-field-source', field));
+    ts.forEachChild(node, walk);
+  };
+  walk(tree); return found;
+}

package/design-local-contracts.mjs

@@ -0,0 +1,15 @@
+import { object, text, identifier, integer, array, record, sha256 } from './local-contract-types.mjs';
+import { DESIGN_SITE_SCHEMA, DESIGN_RULES_SCHEMA } from './design-contracts.mjs';
+
+const base = { repositoryRoot: text, home: text, flowId: identifier, designId: identifier, revision: integer(1) };
+const required = ['repositoryRoot', 'home', 'flowId', 'designId', 'revision'];
+export const DESIGN_LOCAL_OPERATION_SCHEMAS = {
+  'design-browser-info': object({ browserExecutablePath: text }, ['browserExecutablePath']),
+  'design-flow': object({ ...base, site: DESIGN_SITE_SCHEMA }, [...required, 'site']),
+  'design-research': object({ ...base, layoutReferences: { ...array(object({ url: text, rationale: text }, ['url', 'rationale']), 2), maxItems: 8 },
+    frameworks: { ...array(record), maxItems: 16 } }, [...required, 'layoutReferences', 'frameworks']),
+  'design-propose': object({ ...base, mockups: { ...array(record, 2), maxItems: 512 }, rules: DESIGN_RULES_SCHEMA }, [...required, 'mockups', 'rules']),
+  'design-status': object(base, required),
+  'design-verify': object({ repositoryRoot: text, home: text, flowId: identifier, acceptedPlan: record, validationContext: record, baselineDigest: sha256,
+    baseUrl: text, browserExecutablePath: text }, ['repositoryRoot', 'home', 'flowId', 'acceptedPlan', 'validationContext', 'baselineDigest', 'baseUrl', 'browserExecutablePath']),
+};

package/design-operations.mjs

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { sha256, canonical } from './local-integrity.mjs';
+import { writeMutationFile14 } from './local-mutation-files.mjs';
+import { designSchema } from './design-contracts.mjs';
+import { validateDesignSite, validateDesignPolicy, designDigest, designBaselineDigest, designFail } from './design-policy.mjs';
+import { designDirectory, designLoad, designSave, designMermaid, designCopy, assertDesignArtifacts, captureDesignSourceBaseline } from './design-store.mjs';
+import { fetchDesignReference, frameworkBinding, FRAMEWORK_DOC_HOSTS, assertFrozenDesignFrameworks } from './design-research.mjs';
+import { assertDesignDeclaration } from './design-gate.mjs';
+import { verifyDesignBrowser } from './design-browser.mjs';
+import { readDesignBrowserIdentity } from './design-browser-identity.mjs';
+
+export async function recordDesignFlow(input) {
+  const site = validateDesignSite(input.site), directory = await designDirectory(input), diagram = designMermaid(site);
+  const file = path.join(directory, 'site-flow.mmd'); await writeMutationFile14(file, Buffer.from(diagram));
+  const flow = { site, flow: { path: file, sha256: sha256(diagram), bytes: Buffer.byteLength(diagram) },
+    flowDigest: designDigest(site), flowRecordedAt: new Date().toISOString() };
+  await designSave(directory, 'flow.json', flow);
+  return { status: 'recorded', ...flow, nextStep: 'design-research', grantsWriteAuthority: false };
+}
+export async function recordDesignResearch(input) {
+  const directory = await designDirectory(input), flow = await designLoad(directory, 'flow.json'), sources = [], frameworks = [];
+  if (!Array.isArray(input.layoutReferences) || input.layoutReferences.length < 2 || input.layoutReferences.length > 8
+    || !Array.isArray(input.frameworks) || input.frameworks.length > 16) designFail('RESEARCH', 'Provide two to eight actual layout references and the declared frameworks');
+  for (const reference of input.layoutReferences) {
+    if (!reference.rationale?.trim()) designFail('RESEARCH', 'Explain why each mainstream layout fits these pages; popularity cannot be assumed');
+    sources.push({ url: reference.url, ...await fetchDesignReference(reference.url), purpose: 'layout', rationale: reference.rationale });
+  }
+  for (const supplied of input.frameworks) {
+    const framework = await frameworkBinding(input, supplied); frameworks.push(framework);
+    for (const url of framework.officialUrls) {
+      const fetched = await fetchDesignReference(url);
+      if (!FRAMEWORK_DOC_HOSTS[framework.packageName].includes(new URL(fetched.finalUrl).hostname)) designFail('FRAMEWORK', 'Official documentation redirected outside its official host');
+      sources.push({ url, ...fetched, purpose: 'framework', rationale: `Official conventions for ${framework.packageName} ${framework.version}` });
+      framework.officialUrls[framework.officialUrls.indexOf(url)] = fetched.finalUrl;
+    }
+  }
+  const result = { ...flow, sources, frameworks, researchRecordedAt: new Date().toISOString() };
+  await designSave(directory, 'research.json', result);
+  return { status: 'recorded', sources, frameworks, nextStep: 'generate-images-then-design-propose', grantsWriteAuthority: false };
+}
+export async function proposeDesign(input) {
+  const directory = await designDirectory(input), research = await designLoad(directory, 'research.json');
+  if (Date.now() - Date.parse(research.researchRecordedAt) > 30 * 86400_000) designFail('RESEARCH_STALE', 'Refresh current internet references in a new design revision');
+  const rules = designSchema('rules', input.rules), mockups = [];
+  const browser = await readDesignBrowserIdentity({ browserExecutablePath: rules.browser.executablePath });
+  if (canonical(browser) !== canonical(rules.browser)) designFail('BROWSER_CHANGED', 'Use the actual configured browser identity before confirming this design');
+  if (!Array.isArray(input.mockups) || input.mockups.length < 2 || input.mockups.length > 512) designFail('MOCKUPS', 'Create actual page/state mockups or prototypes after research');
+  for (const [index, item] of input.mockups.entries()) {
+    const image = await designCopy(directory, `mockup-${index}.png`, item.image.path);
+    const receipt = await designCopy(directory, `generation-${index}.json`, item.generation.receipt.path);
+    mockups.push({ ...item, image, generation: { ...item.generation, receipt } });
+  }
+  const body = { schemaVersion: 'entrorove.design-policy/1.0', designId: input.designId, flowId: input.flowId,
+    revision: input.revision, ...research, mockups, rules, sourceBaseline: await captureDesignSourceBaseline(input, directory, rules.uiPaths),
+    mockupsRecordedAt: new Date().toISOString() };
+  const design = validateDesignPolicy({ ...body, baselineDigest: designBaselineDigest(body) });
+  await assertDesignArtifacts(design, input);
+  await assertFrozenDesignFrameworks(input, design);
+  assertDesignDeclaration({ design }, design.rules.uiPaths);
+  await designSave(directory, 'proposal.json', design);
+  return { status: 'needs-human-confirmation', design, proposalPath: path.join(directory, 'proposal.json'),
+    nextStep: 'workflow-design-review', grantsWriteAuthority: false,
+    instruction: 'Show the whole-site flow, reference links, generated images and exact component/token/interaction rules to the user. Obtain the original design-only human confirmation before UI code preparation, then carry its designApproval in the original discipline policy. All original scope, source, plan and mutation gates still apply.' };
+}
+export async function readDesignStatus(input) {
+  const directory = await designDirectory(input), records = {};
+  for (const name of ['flow', 'research', 'proposal']) {
+    try { records[name] = await designLoad(directory, `${name}.json`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const entries = await fs.readdir(directory), attempts = entries.filter(name => /^browser-[a-f0-9-]+-start\.json$/.test(name)).sort().map(name => {
+    const id = name.replace(/-start\.json$/, '');
+    return { attemptId: id, startPath: path.join(directory, name), status: entries.includes(`${id}.json`) ? 'reported'
+      : entries.includes(`${id}-launch-failed.json`) ? 'launch-failed' : 'outcome-unknown',
+    ...(entries.includes(`${id}.json`) ? { reportPath: path.join(directory, `${id}.json`) } : {}) };
+  });
+  return { status: records.proposal ? 'awaiting-cloud-confirmation' : records.research ? 'awaiting-generated-images' : 'awaiting-research', records, attempts, grantsWriteAuthority: false };
+}
+export const DESIGN_LOCAL_OPERATIONS = Object.freeze({ 'design-browser-info': readDesignBrowserIdentity, 'design-flow': recordDesignFlow, 'design-research': recordDesignResearch,
+  'design-propose': proposeDesign, 'design-status': readDesignStatus, 'design-verify': verifyDesignBrowser });

package/design-policy.d.mts

@@ -0,0 +1,5 @@
+export function designFail(code: string, message: string): never;
+export function designDigest(value: unknown): string;
+export function validateDesignSite(value: unknown): Record<string, any>;
+export function validateDesignPolicy(value: unknown): Record<string, any>;
+export function validateDesignReport(value: unknown, policy: unknown): Record<string, any>;

package/design-policy.mjs

@@ -0,0 +1,137 @@
+import { canonical, sha256 } from './local-integrity.mjs';
+import { designSchema } from './design-contracts.mjs';
+import { FRAMEWORK_DOC_HOSTS } from './design-frameworks.mjs';
+
+export function designFail(code, message) { throw Object.assign(new Error(message), { code: `ENTROROVE_DESIGN_${code}` }); }
+export const designDigest = value => sha256(canonical(value));
+export function validateDesignSite(raw) {
+  const site = designSchema('site', raw), pages = new Map(site.pages.map(page => [page.id, page]));
+  if (pages.size !== site.pages.length || new Set(site.edges.map(edge => edge.id)).size !== site.edges.length
+    || !site.pages.some(page => page.entry) || new Set(site.roles).size !== site.roles.length) designFail('FLOW', 'Whole-site roles, pages, edges and entry points must be unique');
+  for (const page of site.pages) {
+    if (page.roles.some(role => !site.roles.includes(role)) || !page.states.includes('default')
+      || new Set(page.states).size !== page.states.length || page.publicFields.some(field => page.internalFields.includes(field))) {
+      designFail('FLOW', 'Every page needs original roles, a default state and disjoint public/internal field contracts');
+    }
+  }
+  for (const edge of site.edges) if (!pages.has(edge.from) || !pages.has(edge.to)) designFail('FLOW', 'Every action must connect declared pages');
+  const reachable = new Set(site.pages.filter(page => page.entry).map(page => page.id));
+  for (let i = 0; i < pages.size; i++) for (const edge of site.edges) if (reachable.has(edge.from)) reachable.add(edge.to);
+  if (reachable.size !== pages.size) designFail('FLOW', 'Whole-site flow contains an unreachable page');
+  for (const page of site.pages) if (site.edges.some(edge => edge.from === page.id && ['save', 'delete'].includes(edge.kind))
+    && (!page.states.includes('error') || !site.edges.some(edge => edge.from === page.id && edge.kind === 'cancel'))) {
+    designFail('FLOW', 'Mutation pages require explicit failure and cancel paths');
+  }
+  return site;
+}
+export function designBaselineDigest(value) { const { baselineDigest, ...body } = value; return designDigest(body); }
+const imageKey = mockup => `${mockup.pageId}/${mockup.stateId}/${mockup.theme}/${mockup.viewport.width}x${mockup.viewport.height}`;
+function validateDesignSources(policy) {
+  for (const source of policy.sources) {
+    for (const value of [source.url, source.finalUrl]) {
+      let url; try { url = new URL(value); } catch { designFail('RESEARCH', 'Research needs actual public HTTPS references'); }
+      if (url.protocol !== 'https:' || url.username || url.password || url.hash || url.port && url.port !== '443'
+        || !/^[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(url.hostname)
+        || /(^|\.)(localhost|local|internal|test|invalid)$/.test(url.hostname)
+        || [...url.searchParams.keys()].some(key => /token|secret|password|key|signature|credential/i.test(key))) designFail('RESEARCH', 'Keep credentials and private references out of design evidence');
+    }
+    const retrieved = Date.parse(source.retrievedAt), recorded = Date.parse(policy.researchRecordedAt);
+    if (!Number.isFinite(retrieved) || retrieved > recorded || recorded - retrieved > 30 * 86400_000) designFail('RESEARCH_STALE', 'Current layout and framework documentation must be fetched before the research stage closes');
+  }
+  if (new Set(policy.frameworks.map(framework => framework.packageName)).size !== policy.frameworks.length) designFail('FRAMEWORK', 'Framework versions must be unambiguous');
+  for (const framework of policy.frameworks) if (!FRAMEWORK_DOC_HOSTS[framework.packageName]
+    || framework.officialUrls.some(url => !FRAMEWORK_DOC_HOSTS[framework.packageName].includes(new URL(url).hostname))) designFail('FRAMEWORK', 'Use the declared framework official documentation hosts');
+}
+export function validateDesignPolicy(raw) {
+  const policy = designSchema('policy', raw), { site, rules } = policy;
+  let preview; try { preview = new URL(rules.previewOrigin); } catch { designFail('PREVIEW', 'Preview must be an exact isolated local origin'); }
+  if (preview.href !== rules.previewOrigin || preview.hostname !== '127.0.0.1' || !preview.port) designFail('PREVIEW', 'Approve the exact isolated preview before UI implementation');
+  validateDesignSite(site);
+  if (policy.baselineDigest !== designBaselineDigest(policy) || policy.flowDigest !== designDigest(site)) designFail('BASELINE_CHANGED', 'Design bytes differ from the exact proposal baseline');
+  const times = [policy.flowRecordedAt, policy.researchRecordedAt, policy.mockupsRecordedAt].map(Date.parse);
+  if (times.some(t => !Number.isFinite(t) || t > Date.now() + 5000) || times[0] > times[1] || times[1] > times[2]) designFail('ORDER', 'Record whole-site flow, internet research, then mockups or prototypes in order');
+  validateDesignSources(policy);
+  const layouts = policy.sources.filter(source => source.purpose === 'layout');
+  if (new Set(layouts.map(source => new URL(source.finalUrl).hostname)).size < 2) designFail('RESEARCH', 'Use current layout references from at least two independent sites with suitability reasons');
+  for (const framework of policy.frameworks) for (const url of framework.officialUrls) {
+    if (!policy.sources.some(source => source.purpose === 'framework' && source.finalUrl === url)) designFail('FRAMEWORK', 'Every declared framework needs fetched official documentation');
+  }
+  if (!rules.uiPaths.includes(rules.tokenPath) || rules.stylePaths.some(p => !rules.uiPaths.includes(p))
+    || rules.uiPaths.some(p => !rules.verificationPaths.includes(p))) designFail('RULES', 'Verification covers every UI file; token and style sources belong to the approved UI paths');
+  if (new Set(policy.sourceBaseline.map(file => file.path)).size !== rules.uiPaths.length
+    || policy.sourceBaseline.length !== rules.uiPaths.length
+    || rules.uiPaths.some(name => !policy.sourceBaseline.some(file => file.path === name))) designFail('BASELINE', 'Every UI source needs its original existing or absent baseline before implementation');
+  const keys = policy.mockups.map(imageKey);
+  if (new Set(keys).size !== keys.length) designFail('MOCKUPS', 'Duplicate mockups cannot substitute for page and state coverage');
+  for (const mockup of policy.mockups) {
+    const page = site.pages.find(item => item.id === mockup.pageId);
+    if (!page?.states.includes(mockup.stateId)) designFail('MOCKUPS', 'Mockups must map to real flow pages and states');
+  }
+  for (const page of site.pages) for (const state of page.states) for (const theme of ['light', 'dark']) {
+    if (!policy.mockups.some(image => image.pageId === page.id && image.stateId === state && image.theme === theme)) designFail('MOCKUPS', `Missing mockup/prototype: ${page.id}/${state}/${theme}`);
+  }
+  validateDesignScenarios(policy);
+  return policy;
+}
+function validateDesignScenarios(policy) {
+  const { site, rules, mockups } = policy, used = new Set(), edges = new Set();
+  for (const scenario of rules.scenarios) {
+    if (!mockups[scenario.mockupIndex] || used.has(scenario.mockupIndex)) designFail('COVERAGE', 'Each mockup needs exactly one executable browser scenario');
+    used.add(scenario.mockupIndex);
+    const page = site.pages.find(item => item.id === scenario.entryPageId);
+    if (!page || !scenario.route.startsWith('/') || scenario.route.startsWith('//') || /[\\\r\n]/.test(scenario.route)) designFail('COVERAGE', 'Browser scenarios require a bounded local route');
+    const assertions = [...scenario.checks, ...scenario.steps.flatMap(step => [...step.checks, ...(step.readBack?.afterReload ?? [])])];
+    if (!assertions.some(check => check.kind === 'bounds') || !assertions.some(check => check.kind === 'style')) designFail('VISUAL', 'Each scenario needs frozen layout bounds and computed style checks');
+    for (const check of assertions) {
+      if (['text', 'value', 'style'].includes(check.kind) && typeof check.value !== 'string'
+        || check.kind === 'count' && !Number.isInteger(check.count) || check.kind === 'bounds' && !check.bounds
+        || check.kind === 'style' && !check.property) designFail('CHECKS', 'Browser assertions require exact expected values');
+    }
+    let cursor = page.id;
+    for (const step of scenario.steps) {
+      const edge = site.edges.find(item => item.id === step.edgeId);
+      if (!edge || edge.from !== cursor) designFail('COVERAGE', 'Browser actions must follow the original whole-site page transitions');
+      cursor = edge.to;
+      edges.add(edge.id);
+      if (!['save', 'delete'].includes(edge.kind) && step.mutations.length) designFail('INTERACTION', 'Open, edit, input, navigation and cancel actions must not save data');
+      if (['save', 'delete'].includes(edge.kind)) validateReadBack(step, edge, site.pages.find(item => item.id === edge.to), policy);
+    }
+    if (cursor !== mockups[scenario.mockupIndex].pageId) designFail('COVERAGE', 'The final screen must correspond to its approved mockup');
+  }
+  if (used.size !== mockups.length || site.edges.some(edge => !edges.has(edge.id))) designFail('COVERAGE', 'Browser scenarios must cover every approved mockup and flow action');
+}
+function validateReadBack(step, edge, page, policy) {
+  const proof = step.readBack;
+  if (!proof || proof.kind === 'http' && (!step.mutations.length || !proof.path || !proof.statusBefore || !proof.statusAfter)
+    || proof.kind === 'local-storage' && (!proof.key || step.mutations.length)) designFail('STATE_PROOF', 'A save/delete needs actual HTTP or local storage state read-back and reload assertions');
+  if (proof.kind === 'http') {
+    const target = new URL(proof.path, policy.rules.previewOrigin);
+    if (target.origin !== new URL(policy.rules.previewOrigin).origin || /[\\\r\n]/.test(proof.path)) designFail('STATE_PROOF', 'Read-back stays inside the approved isolated preview');
+  }
+  const succeeded = proof.kind === 'local-storage' || step.mutations.some(item => item.status < 300);
+  if (succeeded === (canonical(proof.before) === canonical(proof.after))) designFail('STATE_PROOF', 'Successful commits must change the declared state; failed commits must preserve it');
+  for (const expected of [proof.before, proof.after]) if (expected && Object.keys(expected).some(key => !page.publicFields.includes(key))) designFail('STATE_PROOF', 'Only the original public field projection can be checked or rendered');
+  if (proof.after && Object.keys(proof.after).some(field => !proof.afterReload.some(check => check.field === field && ['text', 'value'].includes(check.kind)))
+    || !proof.after && !proof.afterReload.some(check => check.kind === 'hidden')) designFail('STATE_PROOF', 'Reload must verify every saved public field or the removed record');
+}
+export function validateDesignReport(raw, policy) {
+  const report = designSchema('report', raw), { reportDigest, ...body } = report;
+  validateDesignPolicy(policy);
+  if (designDigest(body) !== reportDigest || report.baselineDigest !== policy.baselineDigest
+    || report.results.length !== policy.rules.scenarios.length || !Number.isFinite(Date.parse(report.startedAt))
+    || !Number.isFinite(Date.parse(report.finishedAt)) || Date.parse(report.finishedAt) < Date.parse(report.startedAt)
+    || Date.parse(report.startedAt) < Date.parse(policy.mockupsRecordedAt)
+    || Date.parse(report.finishedAt) > Date.now() + 5000 || !/^playwright-core\/1\.64\.1 chromium\/[0-9]/.test(report.engine)) designFail('ACCEPTANCE', 'Browser report lost its exact design baseline or coverage');
+  const indexes = new Set();
+  for (const result of report.results) {
+    const scenario = policy.rules.scenarios.find(item => item.mockupIndex === result.mockupIndex);
+    const count = scenario && scenario.checks.length + scenario.steps.reduce((sum, step) => sum + step.checks.length, 0);
+    if (!scenario || indexes.has(result.mockupIndex) || result.failures.length || result.checks !== count
+      || result.steps !== scenario.steps.length
+      || result.stateChecks !== scenario.steps.filter(step => step.readBack).length * 2 + Number(scenario.steps.some(step => step.readBack))) designFail('ACCEPTANCE', 'Failed, incomplete or duplicate functional/visual evidence cannot pass');
+    indexes.add(result.mockupIndex);
+  }
+  if (new Set(report.sourceManifest.map(file => file.path)).size !== report.sourceManifest.length
+    || policy.rules.uiPaths.some(name => !report.sourceManifest.some(file => file.path === name))) designFail('ACCEPTANCE', 'Acceptance must bind every approved UI file');
+  return report;
+}

package/design-release.mjs

@@ -0,0 +1,25 @@
+export const DESIGN_GATE_SOURCE_FILES = [
+  "design-browser-checks.mjs",
+  "design-browser-identity.mjs",
+  "design-browser-state.mjs",
+  "design-browser.mjs",
+  "design-context.mjs",
+  "design-contracts.d.mts",
+  "design-contracts.mjs",
+  "design-declaration.mjs",
+  "design-frameworks.mjs",
+  "design-gate.mjs",
+  "design-lint.mjs",
+  "design-local-contracts.mjs",
+  "design-operations.mjs",
+  "design-policy.d.mts",
+  "design-policy.mjs",
+  "design-research.mjs",
+  "design-runner.mjs",
+  "design-store.mjs",
+  "design-ui.mjs",
+  "DESIGN-GATES.md",
+  "design-release.mjs"
+];
+export const designGateReleaseLabels = Object.fromEntries(DESIGN_GATE_SOURCE_FILES.map(file => [file,
+  { zh: "全站流程、设计确认与真实功能视觉验收门禁", en: "whole-site flow, design approval and actual functional/visual acceptance gates" }]));

package/design-research.mjs

@@ -0,0 +1,99 @@
+import https from 'node:https';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { parse as yaml } from 'yaml';
+import { mutationRead14, mutationTarget14 } from './local-mutation-files.mjs';
+import { sha256 } from './local-integrity.mjs';
+import { designFail } from './design-policy.mjs';
+
+import { FRAMEWORK_DOC_HOSTS } from './design-frameworks.mjs';
+export { FRAMEWORK_DOC_HOSTS } from './design-frameworks.mjs';
+export function researchUrl(value) {
+  let url; try { url = new URL(value); } catch { designFail('RESEARCH_URL', 'Research requires an absolute public HTTPS URL'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.port && url.port !== '443' || url.hash
+    || net.isIP(url.hostname) || /(^|\.)(localhost|local|internal|test|invalid)$/i.test(url.hostname)
+    || [...url.searchParams.keys()].some(key => /token|secret|password|key|signature|credential/i.test(key))) designFail('RESEARCH_URL', 'Research URLs must be public, credential-free HTTPS references');
+  return url;
+}
+function publicIp(address) {
+  if (net.isIP(address) !== 4) return false;
+  const [a, b, c] = address.split('.').map(Number);
+  return ![0, 10, 127].includes(a) && a < 224 && !(a === 169 && b === 254)
+    && !(a === 172 && b >= 16 && b <= 31) && !(a === 192 && (b === 168 || b === 0 && [0, 2].includes(c)))
+    && !(a === 198 && ([18, 19].includes(b) || b === 51 && c === 100)) && !(a === 203 && b === 0 && c === 113)
+    && !(a === 100 && b >= 64 && b <= 127);
+}
+export async function fetchDesignReference(value, redirects = 0) {
+  const url = researchUrl(value), addresses = await dns.lookup(url.hostname, { all: true, family: 4 });
+  if (!addresses.length || addresses.some(item => !publicIp(item.address))) designFail('RESEARCH_URL', 'Research hostname resolves outside the public internet');
+  const result = await new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { accept: 'text/html,text/plain,application/json', 'user-agent': 'Entrorove design research' },
+      lookup: (_host, options, callback) => callback(null, options.all ? [addresses[0]] : addresses[0].address, 4) }, response => {
+      const chunks = []; let bytes = 0;
+      response.on('data', chunk => { bytes += chunk.length; if (bytes > 2_097_152) req.destroy(Object.assign(new Error('Research response exceeds 2 MiB'), { code: 'ENTROROVE_DESIGN_RESEARCH_SIZE' })); else chunks.push(chunk); });
+      response.on('end', () => resolve({ status: response.statusCode, location: response.headers.location, type: response.headers['content-type'], body: Buffer.concat(chunks) }));
+      response.on('error', reject);
+    });
+    req.setTimeout(15_000, () => req.destroy(Object.assign(new Error('Research fetch timed out'), { code: 'ENTROROVE_DESIGN_RESEARCH_TIMEOUT' })));
+    req.on('error', reject);
+  });
+  if ([301, 302, 303, 307, 308].includes(result.status)) {
+    if (!result.location || redirects >= 4) designFail('RESEARCH_REDIRECT', 'Research redirect did not resolve to a bounded public reference');
+    return fetchDesignReference(new URL(result.location, url).href, redirects + 1);
+  }
+  if (result.status !== 200 || !/^(text\/(html|plain)|application\/json)\b/i.test(result.type ?? '') || result.body.length < 80) designFail('RESEARCH_HTTP', 'Official and layout references must return actual readable documentation');
+  return { finalUrl: url.href, sha256: sha256(result.body), bytes: result.body.length, retrievedAt: new Date().toISOString() };
+}
+function lockedVersion(raw, lockPath, packageName, packagePath) {
+  if (path.basename(lockPath) === 'package-lock.json') {
+    const lock = JSON.parse(raw), prefix = path.posix.dirname(packagePath), base = prefix === '.' ? '' : `${prefix}/`;
+    return lock.packages?.[`${base}node_modules/${packageName}`]?.version ?? lock.packages?.[`node_modules/${packageName}`]?.version;
+  }
+  if (path.basename(lockPath) === 'pnpm-lock.yaml') {
+    const lock = yaml(raw), importer = lock.importers?.[path.posix.dirname(packagePath)], entry = importer?.dependencies?.[packageName] ?? importer?.devDependencies?.[packageName];
+    return String(entry?.version ?? '').replace(/\(.*/, '');
+  }
+  designFail('FRAMEWORK_LOCK', 'Resolve the declared framework from package-lock.json or pnpm-lock.yaml; unsupported locks stay unverified');
+}
+export async function frameworkBinding(input, framework) {
+  const hosts = FRAMEWORK_DOC_HOSTS[framework.packageName];
+  if (!hosts || !framework.officialUrls?.length || framework.officialUrls.some(value => !hosts.includes(researchUrl(value).hostname))) designFail('FRAMEWORK', 'Declared frameworks require recognized official documentation hosts');
+  const pkg = await mutationRead14(input, input.repositoryRoot, framework.packagePath), lock = await mutationRead14(input, input.repositoryRoot, framework.lockPath);
+  const declared = JSON.parse(pkg.content.toString('utf8'));
+  if (!(declared.dependencies?.[framework.packageName] ?? declared.devDependencies?.[framework.packageName])
+    || lockedVersion(lock.content.toString('utf8'), framework.lockPath, framework.packageName, framework.packagePath) !== framework.version) designFail('FRAMEWORK_VERSION', 'Official framework conventions must bind the exact version in the actual dependency lock');
+  return { ...framework, packageSha256: pkg.sha256, lockSha256: lock.sha256 };
+}
+export async function assertDeclaredDesignFrameworks(input, design) {
+  const checked = new Set(), declared = new Set(design.frameworks.map(framework => framework.packageName));
+  for (const source of design.rules.uiPaths) {
+    let directory = path.posix.dirname(source);
+    while (true) {
+      const name = directory === '.' ? 'package.json' : `${directory}/package.json`;
+      const file = await mutationTarget14(input.repositoryRoot, name, true);
+      if (file.exists) {
+        if (!checked.has(name)) {
+          const actual = JSON.parse((await mutationRead14(input, input.repositoryRoot, name)).content.toString('utf8'));
+          const packages = { ...actual.dependencies, ...actual.devDependencies };
+          if (Object.keys(packages).some(packageName => Object.hasOwn(FRAMEWORK_DOC_HOSTS, packageName) && !declared.has(packageName))) designFail('FRAMEWORK_MISSING', 'Research every actual declared framework in the nearest UI package using its official documentation and locked version');
+          checked.add(name);
+        }
+        break;
+      }
+      if (directory === '.') break;
+      directory = path.posix.dirname(directory);
+    }
+  }
+  for (const module of design.rules.componentModules) if (!module.module.startsWith('.')
+    && !design.frameworks.some(framework => module.module === framework.packageName || module.module.startsWith(`${framework.packageName}/`))) designFail('FRAMEWORK_MISSING', 'External component libraries require their own declared official framework documentation');
+  for (const module of design.rules.frameworkStyleImports ?? []) if (!design.frameworks.some(framework => module.startsWith(`${framework.packageName}/`))) designFail('FRAMEWORK_MISSING', 'Framework theme imports must belong to an approved, version-bound framework');
+  for (const name of design.rules.uiPaths) if (/\.vue$/i.test(name) && !declared.has('vue') || /\.svelte$/i.test(name) && !declared.has('svelte')) designFail('FRAMEWORK_MISSING', 'Framework-specific UI source cannot skip its official conventions');
+}
+export async function assertFrozenDesignFrameworks(input, design) {
+  await assertDeclaredDesignFrameworks(input, design);
+  for (const framework of design.frameworks) {
+    const bound = await frameworkBinding(input, framework);
+    if (bound.packageSha256 !== framework.packageSha256 || bound.lockSha256 !== framework.lockSha256) designFail('FRAMEWORK_CHANGED', 'Framework version or dependency bytes changed after design confirmation');
+  }
+}

package/design-runner.mjs

@@ -0,0 +1,31 @@
+import { mutationRead14, mutationTarget14 } from './local-mutation-files.mjs';
+import { assertDesignDeclaration } from './design-declaration.mjs';
+import { assertDesignWrite } from './design-gate.mjs';
+import { designUiCandidate } from './design-ui.mjs';
+import { designFail } from './design-policy.mjs';
+
+export async function designRunnerBefore(input, authority) {
+  const policy = authority.plan.policy.discipline, originals = new Map();
+  if (!policy || policy.access === 'read-only') return originals;
+  assertDesignDeclaration(policy, policy.writes.flatMap(write => [write.targetPath, ...(write.destinationPath ? [write.destinationPath] : [])]));
+  for (const write of policy.writes) {
+    const target = await mutationTarget14(authority.root, write.targetPath, true);
+    const source = target.exists ? (await mutationRead14(input, authority.root, write.targetPath)).content.toString('utf8') : '';
+    originals.set(write.targetPath, source);
+    if (designUiCandidate(write.targetPath, source)) await assertDesignWrite(input,
+      { flowId: input.flowId, disciplinePolicy: policy }, write.targetPath, source, source);
+  }
+  return originals;
+}
+export async function designRunnerAfter(input, authority, changed, originals) {
+  const policy = authority.plan.policy.discipline;
+  for (const name of changed) {
+    const target = await mutationTarget14(authority.root, name, true);
+    const source = target.exists && target.stat.size <= 2_097_152
+      ? (await mutationRead14(input, authority.root, name)).content.toString('utf8') : '';
+    const before = originals.get(name) ?? '';
+    if (!designUiCandidate(name, before, source) && !policy?.design?.rules.uiPaths.includes(name)) continue;
+    if (!policy?.writes.some(write => write.targetPath === name || write.destinationPath === name)) designFail('UNDECLARED_WRITE', 'Runner changed an undeclared UI source; preserve the failed run and its unknown effects');
+    await assertDesignWrite(input, { flowId: input.flowId, disciplinePolicy: policy }, name, before, source);
+  }
+}