@entrorove/skill 0.1.64 → 0.1.67

package/design-browser.mjs

@@ -0,0 +1,181 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { chromium } from 'playwright-core';
+import { designFail, validateDesignPolicy, validateDesignReport, designDigest } from './design-policy.mjs';
+import { disciplineApprovedPolicy } from './local-discipline-contracts.mjs';
+import { designDirectory, designSave, assertDesignArtifacts, designSourceManifest, sameDesignBytes, designOriginalSource } from './design-store.mjs';
+import { writeMutationFile14 } from './local-mutation-files.mjs';
+import { sha256 } from './local-integrity.mjs';
+import { assertDesignLint } from './design-lint.mjs';
+import { assertFrozenDesignFrameworks } from './design-research.mjs';
+import { designUiAsset } from './design-ui.mjs';
+import { verifyOriginalWorkflowPlan } from './workflow-local-runner.mjs';
+import { assertBudgetRunnerAllowed } from './local-budget-reads.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { designValidationContext, designContextSources } from './design-context.mjs';
+import { readDesignBrowserIdentity } from './design-browser-identity.mjs';
+import { browserChecks, networkCheck, publicFieldCheck, installSuccessMonitor, monitorSuccess, previewUrl } from './design-browser-checks.mjs';
+import { checkBrowserState, beginBrowserAction, checkNonCommitStorage } from './design-browser-state.mjs';
+
+function matchesPage(url, pageContract, base) {
+  const route = pageContract.route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/:[\w]+/g, '[^/]+');
+  return url.origin === base.origin && new RegExp(`^${route}$`).test(url.pathname);
+}
+
+async function verifySources(input, policy) {
+  const { mutationRead14 } = await import('./local-mutation-files.mjs');
+  for (const name of policy.rules.uiPaths) {
+    const { content } = await mutationRead14(input, input.repositoryRoot, name);
+    const original = await designOriginalSource(policy, name), source = designUiAsset(name) ? '' : new TextDecoder('utf-8', { fatal: true }).decode(content);
+    assertDesignLint(policy, name, original, source, original);
+  }
+  return designSourceManifest(input, policy);
+}
+async function scenarioRun(browser, input, policy, scenario, directory, runId, deadlineAt) {
+  const mockup = policy.mockups[scenario.mockupIndex];
+  let pageContract = policy.site.pages.find(item => item.id === scenario.entryPageId), stateChecks = 0, lastReadBack;
+  const base = previewUrl(input.baseUrl), target = new URL(scenario.route, base);
+  if (!matchesPage(target, pageContract, base)) designFail('PREVIEW', 'Scenario route differs from its approved flow page');
+  const context = await browser.newContext({ viewport: mockup.viewport, colorScheme: mockup.theme,
+    reducedMotion: 'reduce', serviceWorkers: 'block', acceptDownloads: false });
+  const page = await context.newPage(), failures = [], mutations = [], requests = new Map();
+  page.setDefaultTimeout(5000);
+  await context.route('**/*', async handler => {
+    const url = new URL(handler.request().url());
+    if (url.origin !== base.origin) { failures.push('external-network'); await handler.abort(); }
+    else await handler.continue();
+  });
+  page.on('request', request => {
+    if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(request.method())) {
+      const event = { method: request.method(), path: new URL(request.url()).pathname, status: null };
+      mutations.push(event); requests.set(request, event);
+    }
+  });
+  page.on('response', response => { const event = requests.get(response.request()); if (event) event.status = response.status(); });
+  page.on('pageerror', () => failures.push('browser-error'));
+  page.on('dialog', async dialog => { failures.push('unexpected-dialog'); await dialog.dismiss(); });
+  try {
+    await installSuccessMonitor(page, scenario.successSelector);
+    await page.goto(target.href, { waitUntil: 'networkidle', timeout: 15_000 });
+    await page.waitForTimeout(policy.rules.settleMs);
+    networkCheck(mutations.splice(0), [], failures);
+    await monitorSuccess(page, failures, false);
+    await checkNonCommitStorage(page, false, failures);
+    await browserChecks(page, scenario.checks, failures);
+    await publicFieldCheck(page, pageContract, policy.rules.forbiddenVisibleText, failures);
+    for (const step of scenario.steps) {
+      if (Date.now() >= deadlineAt) designFail('TIME_LIMIT', 'Browser acceptance reached its original bounded deadline');
+      await assertBudgetRunnerAllowed(input);
+      const edge = policy.site.edges.find(item => item.id === step.edgeId);
+      pageContract = policy.site.pages.find(item => item.id === edge.to);
+      await beginBrowserAction(page);
+      if (step.readBack) {
+        await checkBrowserState(page, step.readBack, 'before', pageContract.publicFields, base, failures); stateChecks++;
+      }
+      const locator = page.locator(step.selector);
+      if (step.action === 'click') await locator.click();
+      else if (step.action === 'fill') await locator.fill(step.value ?? '');
+      else await locator.press(step.value ?? 'Enter');
+      await page.waitForTimeout(policy.rules.settleMs);
+      networkCheck(mutations.splice(0), step.mutations, failures);
+      const commits = ['save', 'delete'].includes(edge.kind);
+      const canSucceed = commits && (step.readBack?.kind === 'local-storage' || step.mutations.some(item => item.status < 300));
+      await checkNonCommitStorage(page, commits, failures);
+      await monitorSuccess(page, failures, canSucceed);
+      if (step.readBack) {
+        await checkBrowserState(page, step.readBack, 'after', pageContract.publicFields, base, failures); stateChecks++;
+        lastReadBack = step.readBack;
+      }
+      if (!matchesPage(new URL(page.url()), pageContract, base)) failures.push('flow-page-transition');
+      await browserChecks(page, step.checks, failures);
+      await publicFieldCheck(page, pageContract, policy.rules.forbiddenVisibleText, failures);
+    }
+    if (await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth + 1)) failures.push('horizontal-overflow');
+  } catch { failures.push('browser-scenario-incomplete'); }
+  try {
+    const file = path.join(directory, `${runId}-${scenario.mockupIndex}.png`), bytes = await page.screenshot({ fullPage: true, animations: 'disabled', timeout: 5000 });
+    await writeMutationFile14(file, bytes);
+    if (lastReadBack) {
+      try {
+        await page.reload({ waitUntil: 'networkidle', timeout: 15_000 });
+        await page.waitForTimeout(policy.rules.settleMs);
+        networkCheck(mutations.splice(0), [], failures);
+        await browserChecks(page, lastReadBack.afterReload, failures);
+        await publicFieldCheck(page, pageContract, policy.rules.forbiddenVisibleText, failures); stateChecks++;
+      } catch { failures.push('reload-state-unverified'); }
+    }
+    return { mockupIndex: scenario.mockupIndex,
+      checks: scenario.checks.length + scenario.steps.reduce((count, step) => count + step.checks.length, 0),
+      steps: scenario.steps.length, stateChecks, failures: [...new Set(failures)], screenshot: { path: file, sha256: sha256(bytes), bytes: bytes.length } };
+  } finally { await context.close(); }
+}
+export async function verifyDesignBrowser(input) {
+  await assertBudgetRunnerAllowed(input);
+  const plan = verifyOriginalWorkflowPlan(input.acceptedPlan);
+  const policies = plan.steps.map(step => step.executionPlan.policy.discipline)
+    .filter(policy => policy?.design?.baselineDigest === input.baselineDigest);
+  if (!policies.length || plan.flowId !== input.flowId) designFail('APPROVAL_REQUIRED', 'Use the exact server-signed live original plan and approved design baseline');
+  const discipline = disciplineApprovedPolicy(policies[0]), policy = validateDesignPolicy(discipline.design);
+  const context = await designValidationContext(input, plan, policy);
+  if (policy.flowId !== input.flowId) designFail('BINDING', 'Browser acceptance must retain its original design flow');
+  if (input.baseUrl !== policy.rules.previewOrigin) designFail('PREVIEW', 'Browser tests may use only the exact preview origin approved before UI implementation');
+  const browserIdentity = await readDesignBrowserIdentity(input);
+  if (!sameDesignBytes(browserIdentity, policy.rules.browser)) designFail('BROWSER_CHANGED', 'The executable differs from the browser frozen in this exact approved design');
+  previewUrl(input.baseUrl);
+  await assertDesignArtifacts(policy, input);
+  await assertFrozenDesignFrameworks(input, policy);
+  const sourceManifest = await designContextSources(input, context, await verifySources(input, policy));
+  const directory = await designDirectory({ ...input, designId: policy.designId, revision: policy.revision });
+  return withStateLock(path.join(directory, 'browser-verification.lock'), () => browserAttempt(input, policy, plan, context, sourceManifest, directory));
+}
+async function browserAttempt(input, policy, plan, context, sourceManifest, directory) {
+  const entries = await fs.readdir(directory);
+  for (const name of entries.filter(name => /^browser-[a-f0-9-]+-start\.json$/.test(name))) {
+    const id = name.replace(/-start\.json$/, '');
+    if (!entries.includes(`${id}.json`) && !entries.includes(`${id}-launch-failed.json`)) designFail('OUTCOME_UNKNOWN', 'The original browser attempt has no terminal report. Read design-status and preserve it; do not repeat its preview requests');
+  }
+  const runId = `browser-${randomUUID()}`, startedAt = new Date().toISOString(), results = [];
+  const deadlineAt = Math.min(Date.now() + 300_000, Date.parse(plan.expiresAt), Date.parse(context.expiresAt));
+  await designSave(directory, `${runId}-start.json`, { schemaVersion: 'entrorove.design-attempt/1.0', runId, startedAt,
+    phase: 'running', callerPid: process.pid, baselineDigest: policy.baselineDigest, sourceManifest,
+    planDigest: input.acceptedPlan.authorityReceipt.payloadDigest, deadlineAt: new Date(deadlineAt).toISOString() });
+  let browser;
+  const environment = Object.fromEntries(['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'LC_ALL', 'TZ', 'SystemRoot', 'WINDIR']
+    .filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]]));
+  try { browser = await chromium.launch({ executablePath: policy.rules.browser.executablePath, headless: true, env: environment }); }
+  catch {
+    await designSave(directory, `${runId}-launch-failed.json`, { phase: 'launch-failed', previewRequestsIssued: false, failedAt: new Date().toISOString() });
+    designFail('BROWSER_UNAVAILABLE', 'A compatible local Chromium executable is required; install it before acceptance. No preview requests or pass were issued');
+  }
+  const engine = `playwright-core/1.64.1 chromium/${browser.version()}`;
+  try {
+    for (const scenario of policy.rules.scenarios) {
+      if (Date.now() >= deadlineAt) designFail('TIME_LIMIT', 'Browser acceptance reached its original bounded deadline');
+      await assertBudgetRunnerAllowed(input);
+      const result = await scenarioRun(browser, input, policy, scenario, directory, runId, deadlineAt);
+      results.push(result);
+      await designSave(directory, `${runId}-${scenario.mockupIndex}-result.json`, { result, completedAt: new Date().toISOString(), engine });
+    }
+  } catch (error) {
+    await designSave(directory, `${runId}-interrupted.json`, { phase: 'interrupted', effects: 'unknown-preview-effects',
+      code: error.code ?? 'ENTROROVE_DESIGN_INTERRUPTED', completedScenarios: results.length, recordedAt: new Date().toISOString() });
+    throw error;
+  } finally { await browser.close(); }
+  let after;
+  try {
+    await assertBudgetRunnerAllowed(input);
+    if (Date.now() > deadlineAt) designFail('TIME_LIMIT', 'Browser acceptance exceeded its original authority window');
+    after = await designContextSources(input, context, await designSourceManifest(input, policy));
+  } catch { after = null; }
+  if (!after || !sameDesignBytes(sourceManifest, after)) for (const result of results) result.failures.push('source-or-authority-changed-during-acceptance');
+  const body = { schemaVersion: 'entrorove.design-report/1.0', baselineDigest: policy.baselineDigest, flowId: input.flowId,
+    sourceManifest, testsDigest: context.testsDigest, validationContext: input.validationContext,
+    startedAt, finishedAt: new Date().toISOString(), engine, results };
+  const report = { ...body, reportDigest: designDigest(body) };
+  const reportPath = await designSave(directory, `${runId}.json`, report);
+  try { validateDesignReport(report, policy); }
+  catch (error) { error.reportPath = reportPath; error.reportDigest = report.reportDigest; throw error; }
+  return { status: 'needs-visual-confirmation', report, reportPath, nextStep: 'workflow-design-acceptance',
+    claimsIndependentVerification: false, instruction: 'Show actual browser screenshots beside the approved mockups or prototypes. Obtain the original user visual acceptance; automated checks alone cannot decide aesthetic quality.' };
+}

package/design-context.mjs

@@ -0,0 +1,34 @@
+import { verifyOriginalWorkflowAuthority } from './workflow-local-runner.mjs';
+import { repositoryIntegrityFile } from './local-discipline-repository.mjs';
+import { mutationPath14, mutationRoot14 } from './local-mutation-files.mjs';
+import { sha256 } from './local-integrity.mjs';
+import { designFail } from './design-policy.mjs';
+
+export async function designValidationContext(input, plan, policy) {
+  const context = verifyOriginalWorkflowAuthority(input.validationContext), issued = Date.parse(context.issuedAt), expires = Date.parse(context.expiresAt);
+  if (context.schemaVersion !== 'entrorove.design-validation-context/1.0' || context.purpose !== 'browser-verify-approved-design'
+    || context.flowId !== input.flowId || context.ownerId !== plan.ownerId || context.taskDigest !== plan.taskDigest
+    || context.chainDigest !== plan.chainDigest || context.planDigest !== input.acceptedPlan.authorityReceipt.payloadDigest
+    || context.baselineDigest !== policy.baselineDigest || context.previewOrigin !== policy.rules.previewOrigin
+    || context.repositoryDigest !== sha256(await mutationRoot14(input.repositoryRoot)).slice(0, 32)
+    || !/^[a-f0-9]{64}$/.test(context.testsDigest ?? '') || context.grantsWriteAuthority !== false
+    || !Number.isFinite(issued) || !Number.isFinite(expires) || issued > Date.now() || expires <= Date.now()
+    || expires <= issued || expires - issued > 300_000 || expires > Date.parse(plan.expiresAt)
+    || !Array.isArray(context.sourceManifest) || !context.sourceManifest.length || context.sourceManifest.length > 2048
+    || new Set(context.sourceManifest.map(file => file.path)).size !== context.sourceManifest.length) designFail('TEST_CONTEXT', 'Use the exact live server-signed context of the original successful tests; no write or independent verifier authority is granted');
+  for (const file of context.sourceManifest) {
+    mutationPath14(file.path);
+    if (Object.keys(file).sort().join('|') !== 'path|sha256' || !/^[a-f0-9]{64}$/.test(file.sha256 ?? '')) designFail('TEST_CONTEXT', 'Original test inputs require exact safe paths and SHA-256 hashes');
+  }
+  return context;
+}
+export async function designContextSources(input, context, required) {
+  for (const file of required) if (!context.sourceManifest.some(expected => expected.path === file.path && expected.sha256 === file.sha256)) designFail('TEST_CONTEXT', 'Every UI source, dependency and framework configuration must be part of the successful original test inputs');
+  for (const expected of context.sourceManifest) {
+    // Unselected test inputs receive integrity-only observation, never source
+    // disclosure or new semantic read/data-write permission.
+    const actual = await repositoryIntegrityFile(input.repositoryRoot, expected.path);
+    if (actual.sha256 !== expected.sha256) designFail('SOURCE_CHANGED', 'An original test input changed before or during browser acceptance');
+  }
+  return structuredClone(context.sourceManifest);
+}

package/design-contracts.d.mts

@@ -0,0 +1,4 @@
+export const DESIGN_REPORT_SCHEMA: Record<string, any>;
+export const DESIGN_POLICY_SCHEMA: Record<string, any>;
+export const DESIGN_SITE_SCHEMA: Record<string, any>;
+export const DESIGN_RULES_SCHEMA: Record<string, any>;

package/design-contracts.mjs

@@ -0,0 +1,77 @@
+import Ajv from 'ajv';
+import { object, array, text, identifier, relativePath, sha256, integer } from './local-contract-types.mjs';
+
+const list = (item, min = 1, max = 128) => ({ ...array(item, min), maxItems: max });
+const names = (min = 1) => ({ ...list(identifier, min), uniqueItems: true });
+const words = { ...text, maxLength: 2000 };
+const artifact = object({ path: text, sha256, bytes: integer(1, 8_388_608) }, ['path', 'sha256', 'bytes']);
+const page = object({ id: identifier, route: { ...text, pattern: '^/(?!/)' }, title: words, roles: names(),
+  states: names(), publicFields: names(0), internalFields: names(0), entry: { type: 'boolean' } },
+['id', 'route', 'title', 'roles', 'states', 'publicFields', 'internalFields', 'entry']);
+export const DESIGN_SITE_SCHEMA = object({ id: identifier, requirementIds: names(), roles: names(), pages: list(page),
+  edges: list(object({ id: identifier, from: identifier, to: identifier,
+    kind: { enum: ['navigate', 'open', 'edit', 'fill', 'validate', 'save', 'cancel', 'delete'] }, label: words },
+  ['id', 'from', 'to', 'kind', 'label']), 0, 256) }, ['id', 'requirementIds', 'roles', 'pages', 'edges']);
+const source = object({ url: text, finalUrl: text, sha256, bytes: integer(1, 2_097_152), retrievedAt: text,
+  purpose: { enum: ['layout', 'framework'] }, rationale: words },
+['url', 'finalUrl', 'sha256', 'bytes', 'retrievedAt', 'purpose', 'rationale']);
+const framework = object({ packageName: text, version: text, packagePath: relativePath, packageSha256: sha256,
+  lockPath: relativePath, lockSha256: sha256, officialUrls: list(text, 1, 16) },
+['packageName', 'version', 'packagePath', 'packageSha256', 'lockPath', 'lockSha256', 'officialUrls']);
+const mockup = object({ kind: { enum: ['mockup', 'prototype'] }, pageId: identifier, stateId: identifier, theme: { enum: ['light', 'dark'] },
+  viewport: object({ width: integer(240, 3840), height: integer(240, 2160) }, ['width', 'height']),
+  image: artifact, generation: object({ tool: words, requestId: words, promptSha256: sha256,
+    receipt: artifact }, ['tool', 'requestId', 'promptSha256', 'receipt']) },
+['kind', 'pageId', 'stateId', 'theme', 'viewport', 'image', 'generation']);
+const assertion = object({ kind: { enum: ['visible', 'hidden', 'text', 'value', 'count', 'style', 'bounds'] },
+  field: identifier,
+  selector: words, value: { type: 'string', maxLength: 2000 }, count: integer(0, 1000), property: identifier,
+  bounds: object({ x: integer(0, 3840), y: integer(0, 10000), width: integer(1, 3840), height: integer(1, 10000),
+    tolerance: integer(0, 8) }, ['x', 'y', 'width', 'height', 'tolerance']) }, ['kind', 'selector']);
+const network = object({ method: { enum: ['POST', 'PUT', 'PATCH', 'DELETE'] }, path: { ...text, pattern: '^/(?!/)' },
+  count: integer(1, 8), status: integer(200, 599) }, ['method', 'path', 'count', 'status']);
+const projection = { anyOf: [{ type: 'object', minProperties: 1, maxProperties: 64 }, { type: 'null' }] };
+const readBack = object({ kind: { enum: ['http', 'local-storage'] }, path: { ...text, pattern: '^/(?!/)' }, key: identifier,
+  jsonPointer: { type: 'string', maxLength: 512, pattern: '^(?:/.*)?$' },
+  statusBefore: integer(200, 499), statusAfter: integer(200, 499), before: projection, after: projection,
+  afterReload: list(assertion) }, ['kind', 'before', 'after', 'afterReload']);
+const step = object({ edgeId: identifier, action: { enum: ['click', 'fill', 'press'] }, selector: words,
+  value: { type: 'string', maxLength: 2000 }, checks: list(assertion), mutations: list(network, 0, 8), readBack },
+['edgeId', 'action', 'selector', 'checks', 'mutations']);
+const scenario = object({ mockupIndex: integer(0, 511), entryPageId: identifier, route: { ...text, pattern: '^/(?!/)' }, steps: list(step, 0, 32), checks: list(assertion),
+  successSelector: words }, ['mockupIndex', 'entryPageId', 'route', 'steps', 'checks', 'successSelector']);
+export const DESIGN_RULES_SCHEMA = object({ uiPaths: { ...list(relativePath), uniqueItems: true },
+  previewOrigin: { ...text, pattern: '^http://127\\.0\\.0\\.1:[1-9][0-9]{0,4}/$' },
+  browser: object({ executablePath: text, sha256 }, ['executablePath', 'sha256']),
+  verificationPaths: { ...list(relativePath, 1, 2048), uniqueItems: true },
+  componentModules: list(object({ module: text, exports: names() }, ['module', 'exports']), 0, 64),
+  frameworkStyleImports: { ...list(text, 0, 64), uniqueItems: true },
+  nativeTags: names(), replacements: list(object({ native: identifier, component: identifier }, ['native', 'component']), 0, 32),
+  tokenPath: relativePath, stylePaths: { ...list(relativePath), uniqueItems: true },
+  tokens: { type: 'object', minProperties: 1, maxProperties: 128, patternProperties: { '^--[a-z][a-z0-9-]*$': { ...text, maxLength: 100 } }, additionalProperties: false },
+  settleMs: integer(500, 5000),
+  forbiddenVisibleText: list(words, 0, 128), scenarios: list(scenario, 2, 512) },
+['uiPaths', 'previewOrigin', 'browser', 'verificationPaths', 'componentModules', 'nativeTags', 'replacements', 'tokenPath', 'stylePaths', 'tokens', 'settleMs', 'forbiddenVisibleText', 'scenarios']);
+export const DESIGN_POLICY_SCHEMA = object({ schemaVersion: { const: 'entrorove.design-policy/1.0' },
+  designId: identifier, flowId: identifier, revision: integer(1), site: DESIGN_SITE_SCHEMA, flow: artifact, flowDigest: sha256,
+  flowRecordedAt: text, researchRecordedAt: text, mockupsRecordedAt: text,
+  sources: list(source, 2, 32), frameworks: list(framework, 0, 16), mockups: list(mockup, 2, 512),
+  sourceBaseline: list(object({ path: relativePath, original: { anyOf: [{ ...artifact, properties: { ...artifact.properties, bytes: integer(0, 8_388_608) } }, { type: 'null' }] } }, ['path', 'original'])),
+  rules: DESIGN_RULES_SCHEMA, baselineDigest: sha256 },
+['schemaVersion', 'designId', 'flowId', 'revision', 'site', 'flow', 'flowDigest', 'flowRecordedAt', 'researchRecordedAt',
+  'mockupsRecordedAt', 'sources', 'frameworks', 'mockups', 'sourceBaseline', 'rules', 'baselineDigest']);
+export const DESIGN_REPORT_SCHEMA = object({ schemaVersion: { const: 'entrorove.design-report/1.0' },
+  baselineDigest: sha256, flowId: identifier, testsDigest: sha256, validationContext: { type: 'object' }, sourceManifest: list(object({ path: relativePath, sha256 }, ['path', 'sha256']), 1, 2048),
+  startedAt: text, finishedAt: text, engine: text,
+  results: list(object({ mockupIndex: integer(0, 511), checks: integer(1), steps: integer(0), stateChecks: integer(0),
+    failures: list(identifier, 0), screenshot: artifact }, ['mockupIndex', 'checks', 'steps', 'stateChecks', 'failures', 'screenshot']), 2, 512),
+  reportDigest: sha256 }, ['schemaVersion', 'baselineDigest', 'flowId', 'testsDigest', 'validationContext', 'sourceManifest', 'startedAt', 'finishedAt', 'engine', 'results', 'reportDigest']);
+const ajv = new Ajv({ allErrors: true, strict: true });
+const validators = new Map([['site', DESIGN_SITE_SCHEMA], ['rules', DESIGN_RULES_SCHEMA], ['policy', DESIGN_POLICY_SCHEMA],
+  ['report', DESIGN_REPORT_SCHEMA]].map(([key, schema]) => [key, ajv.compile(schema)]));
+export function designSchema(kind, value) {
+  const validate = validators.get(kind);
+  if (!validate?.(value)) throw Object.assign(new Error(`Invalid design ${kind}: ${validate?.errors?.map(e => e.instancePath || e.keyword).join(', ')}`),
+    { code: 'ENTROROVE_DESIGN_INVALID' });
+  return structuredClone(value);
+}

package/design-declaration.mjs

@@ -0,0 +1,17 @@
+import { designFail, validateDesignPolicy } from './design-policy.mjs';
+import { designUiCandidate } from './design-ui.mjs';
+
+const componentRules = { antd: { button: 'Button', input: 'Input', dialog: 'Modal' },
+  'element-plus': { button: 'ElButton', input: 'ElInput', dialog: 'ElDialog' },
+  '@mui/material': { button: 'Button', input: 'TextField', dialog: 'Dialog' } };
+export function assertDesignDeclaration(policy, paths) {
+  const ui = paths.filter(name => designUiCandidate(name));
+  if (!ui.length && !policy?.design) return;
+  if (!policy?.design) designFail('REQUIRED', 'UI implementation requires whole-site flow, actual internet research, mockups or prototypes and the original human confirmation');
+  const design = validateDesignPolicy(policy.design);
+  if (ui.some(name => !design.rules.uiPaths.includes(name))) designFail('SCOPE', 'Every UI write must belong to the exact approved design');
+  for (const framework of design.frameworks) for (const [native, component] of Object.entries(componentRules[framework.packageName] ?? {})) {
+    if (!design.rules.replacements.some(rule => rule.native === native && rule.component === component)
+      || !design.rules.componentModules.some(module => module.module === framework.packageName && module.exports.includes(component))) designFail('FRAMEWORK_RULES', 'Use the declared component library for its standard controls and dialogs');
+  }
+}

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>;