@entrorove/skill 0.1.71 → 0.1.78

package/design-browser-pages.mjs

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import { designFail } from './design-policy.mjs';
+import { installSuccessMonitor, checkBrowserMonitors } from './design-browser-checks.mjs';
+import { beginBrowserAction } from './design-browser-state.mjs';
+import { browserStorage, browserStepHandoffs } from './design-storage.mjs';
+
+export function matchesDesignPage(url, pageContract, base) {
+  const approved = new URL(pageContract.route, base);
+  const route = approved.pathname.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/:[\w]+/g, '[^/]+');
+  const query = search => { const value = new URLSearchParams(search); value.sort(); return value.toString(); };
+  return approved.origin === base.origin && url.origin === base.origin && !url.username && !url.password
+    && new RegExp(`^${route}$`).test(url.pathname)
+    && (!pageContract.route.split('#')[0].includes('?') || query(approved.search) === query(url.search))
+    && (!approved.hash || approved.hash === url.hash);
+}
+function remaining(deadlineAt, limit = 5000) {
+  const value = deadlineAt - Date.now();
+  if (value <= 0) designFail('TIME_LIMIT', 'Browser acceptance reached its original bounded deadline');
+  return Math.min(limit, value);
+}
+export async function browserPages(context, scenario, base, failures, deadlineAt, settleMs, site) {
+  const pages = [], observed = {}, mutations = [], requests = new Map(), parents = new WeakMap(), writes = [];
+  const storage = browserStorage(base, parents);
+  const binding = `__entroroveDesignRecord_${randomUUID().replaceAll('-', '')}`;
+  await context.exposeBinding(binding, (source, event) => {
+    if (event?.kind === 'storage') {
+      observed.storage = true;
+      if (writes.length < 64) writes.push({ ...event, page: source.page }); else failures.push('storage-observation-limit');
+    }
+    else if (event?.kind === 'success') {
+      observed.success = true;
+      if (event.successfulAcknowledgement !== true) observed.unacknowledged = true;
+    } else failures.push('browser-monitor-invalid');
+  });
+  const keys = scenario.steps.flatMap(step => browserStepHandoffs(step, site.edges.find(edge => edge.id === step.edgeId)))
+    .map(({ area, key }) => ({ area, key }));
+  await installSuccessMonitor(context, scenario.successSelector, binding, keys);
+  await context.route('**/*', async handler => {
+    if (new URL(handler.request().url()).origin !== base.origin) { failures.push('external-network'); await handler.abort(); }
+    else await handler.continue();
+  });
+  context.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);
+    }
+  });
+  context.on('response', response => { const event = requests.get(response.request()); if (event) event.status = response.status(); });
+  context.on('page', page => {
+    pages.push(page); page.setDefaultTimeout(Math.max(1, Math.min(5000, deadlineAt - Date.now())));
+    page.on('pageerror', () => failures.push('browser-error'));
+    page.on('dialog', async dialog => { failures.push('unexpected-dialog'); await dialog.dismiss(); });
+  });
+  return {
+    mutations,
+    mark: () => pages.length,
+    async begin(page) {
+      remaining(deadlineAt);
+      await storage.begin(context, page);
+      for (const page of context.pages()) await beginBrowserAction(page);
+      for (const key of Object.keys(observed)) delete observed[key];
+      writes.length = 0;
+    },
+    async check(commits, canSucceed, handoffs = [], page) {
+      remaining(deadlineAt);
+      for (const page of context.pages()) await checkBrowserMonitors(page, commits || handoffs.length > 0, canSucceed, failures);
+      await storage.check(context, page, handoffs, writes, commits, failures);
+      if (observed.success && (!canSucceed || observed.unacknowledged)) failures.push('premature-success-message');
+    },
+    async next(current, mark, pageContract) {
+      remaining(deadlineAt);
+      const added = pages.slice(mark);
+      if (added.length > 1) { failures.push('ambiguous-popup'); designFail('PREVIEW', 'An action opened multiple unapproved windows'); }
+      let next = current;
+      if (added.length) {
+        next = added[0];
+        if (next.isClosed() || await next.opener() !== current) {
+          failures.push('unverified-popup'); designFail('PREVIEW', 'A popup lost its original triggering page');
+        }
+        parents.set(next, current);
+        await next.waitForURL(url => url.href !== 'about:blank', { timeout: remaining(deadlineAt, 15_000) });
+        if (!matchesDesignPage(new URL(next.url()), pageContract, base)) {
+          failures.push('flow-page-transition'); designFail('PREVIEW', 'The popup did not reach its exact approved page');
+        }
+        await next.waitForLoadState('networkidle', { timeout: remaining(deadlineAt, 15_000) });
+        if (deadlineAt - Date.now() < settleMs) designFail('TIME_LIMIT', 'The popup cannot settle within its original authority window');
+        await next.waitForTimeout(settleMs);
+      } else if (current.isClosed()) {
+        next = parents.get(current);
+        if (!next || next.isClosed()) designFail('PREVIEW', 'The action closed its page without an original live opener');
+      }
+      if (!matchesDesignPage(new URL(next.url()), pageContract, base)) failures.push('flow-page-transition');
+      return next;
+    }
+  };
+}

package/design-browser-state.mjs

@@ -24,6 +24,7 @@ export async function checkBrowserState(page, proof, phase, fields, baseUrl, fai
       actual = value === null ? null : projected(JSON.parse(value), proof.jsonPointer);
     }
     if (expected === null) { if (actual !== null) failures.push('read-back-state'); }
+    else if (fields === null) { if (canonical(actual) !== canonical(expected)) failures.push('handoff-storage-state'); }
     else if (!actual || typeof actual !== 'object' || Array.isArray(actual)
       || Object.keys(actual).some(key => !fields.includes(key))
       || Object.keys(expected).some(key => canonical(actual[key] ?? null) !== canonical(expected[key]))) failures.push('read-back-state');

package/design-browser.mjs

@@ -15,13 +15,11 @@ 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);
-}
+import { browserChecks, networkCheck, publicFieldCheck, previewUrl } from './design-browser-checks.mjs';
+import { checkBrowserState } from './design-browser-state.mjs';
+import { matchesDesignPage, browserPages } from './design-browser-pages.mjs';
+import { assertDesignStageSources, designAcceptanceScope } from './design-stage.mjs';
+import { browserStepHandoffs } from './design-storage.mjs';
 
 async function verifySources(input, policy) {
   const { mutationRead14 } = await import('./local-mutation-files.mjs');
@@ -34,60 +32,51 @@ async function verifySources(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;
+  let pageContract = policy.site.pages.find(item => item.id === scenario.entryPageId), stateChecks = 0, lastReadBack, lastHandoff;
   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');
+  if (!matchesDesignPage(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(); });
+  const failures = [], tracked = await browserPages(context, scenario, base, failures, deadlineAt, policy.rules.settleMs, policy.site), { mutations } = tracked;
+  let page = await context.newPage();
   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 tracked.check(false, false, [], page);
     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);
+      const handoffs = browserStepHandoffs(step, edge), fields = handoffs.length ? null : policy.site.pages.find(item => item.id === edge.to).publicFields;
       pageContract = policy.site.pages.find(item => item.id === edge.to);
-      await beginBrowserAction(page);
+      await tracked.begin(page);
       if (step.readBack) {
-        await checkBrowserState(page, step.readBack, 'before', pageContract.publicFields, base, failures); stateChecks++;
+        await checkBrowserState(page, step.readBack, 'before', fields, base, failures); stateChecks++;
+      }
+      const mark = tracked.mark(), locator = page.locator(step.selector);
+      try {
+        if (step.action === 'click') await locator.click();
+        else if (step.action === 'fill') await locator.fill(step.value ?? '');
+        else await locator.press(step.value ?? 'Enter');
+      } catch (error) {
+        if (step.action !== 'click' || edge.kind !== 'cancel' || !page.isClosed()) throw error;
+        page = await tracked.next(page, mark, pageContract);
       }
-      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);
+      await new Promise(resolve => setTimeout(resolve, policy.rules.settleMs));
+      page = await tracked.next(page, mark, pageContract);
       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);
+      await tracked.check(commits, canSucceed, handoffs, page);
+      if (step.storageHandoffs?.length) stateChecks += 2;
       if (step.readBack) {
-        await checkBrowserState(page, step.readBack, 'after', pageContract.publicFields, base, failures); stateChecks++;
-        lastReadBack = step.readBack;
+        await checkBrowserState(page, step.readBack, 'after', fields, base, failures); stateChecks++;
+        lastReadBack = step.readBack; lastHandoff = handoffs.length > 0;
       }
-      if (!matchesPage(new URL(page.url()), pageContract, base)) failures.push('flow-page-transition');
+      if (!matchesDesignPage(new URL(page.url()), pageContract, base)) designFail('PREVIEW', 'The action did not reach its exact approved page');
       await browserChecks(page, step.checks, failures);
       await publicFieldCheck(page, pageContract, policy.rules.forbiddenVisibleText, failures);
     }
@@ -98,10 +87,14 @@ async function scenarioRun(browser, input, policy, scenario, directory, runId, d
     await writeMutationFile14(file, bytes);
     if (lastReadBack) {
       try {
+        await tracked.begin(page);
         await page.reload({ waitUntil: 'networkidle', timeout: 15_000 });
         await page.waitForTimeout(policy.rules.settleMs);
         networkCheck(mutations.splice(0), [], failures);
+        await tracked.check(false, false, [], page);
+        if (!matchesDesignPage(new URL(page.url()), pageContract, base)) failures.push('flow-page-transition');
         await browserChecks(page, lastReadBack.afterReload, failures);
+        if (lastHandoff) await checkBrowserState(page, lastReadBack, 'after', null, base, failures);
         await publicFieldCheck(page, pageContract, policy.rules.forbiddenVisibleText, failures); stateChecks++;
       } catch { failures.push('reload-state-unverified'); }
     }
@@ -125,6 +118,7 @@ export async function verifyDesignBrowser(input) {
   previewUrl(input.baseUrl);
   await assertDesignArtifacts(policy, input);
   await assertFrozenDesignFrameworks(input, policy);
+  await assertDesignStageSources(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));
@@ -167,6 +161,7 @@ async function browserAttempt(input, policy, plan, context, sourceManifest, dire
     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));
+    await assertDesignStageSources(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,
@@ -177,5 +172,6 @@ async function browserAttempt(input, policy, plan, context, sourceManifest, dire
   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',
+    acceptanceScope: designAcceptanceScope(policy),
     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-contracts.mjs

@@ -1,5 +1,6 @@
 import Ajv from 'ajv';
 import { object, array, text, identifier, relativePath, sha256, integer } from './local-contract-types.mjs';
+import { DESIGN_STAGE_SCHEMA, DESIGN_HANDOFF_SCHEMA } from './design-stage-contracts.mjs';
 
 const list = (item, min = 1, max = 128) => ({ ...array(item, min), maxItems: max });
 const names = (min = 1) => ({ ...list(identifier, min), uniqueItems: true });
@@ -36,11 +37,13 @@ const readBack = object({ kind: { enum: ['http', 'local-storage'] }, path: { ...
   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 },
+  value: { type: 'string', maxLength: 2000 }, checks: list(assertion), mutations: list(network, 0, 8), readBack,
+  storageHandoffs: list(DESIGN_HANDOFF_SCHEMA, 0, 8) },
 ['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 },
+  stage: DESIGN_STAGE_SCHEMA,
   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 },

package/design-declaration.mjs

@@ -9,6 +9,9 @@ export function assertDesignDeclaration(policy, paths) {
   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);
+  const frozen = new Set((design.rules.stage?.readOnlyPages ?? []).flatMap(page => page.sources.map(source => source.path)));
+  if (policy.writes?.some(write => frozen.has(write.targetPath) || frozen.has(write.destinationPath))) designFail('STAGE_READ_ONLY', 'An approved stage cannot declare writes, deletions or moves of its read-only context sources');
+  if (design.rules.stage && policy.writes?.some(write => write.requirementRefs.some(id => !design.rules.stage.requirementIds.includes(id)))) designFail('STAGE', 'Stage writes must retain the exact original requirements selected for this stage');
   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)

package/design-frameworks.mjs

@@ -1,4 +1,5 @@
 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'] });
+  tailwindcss: ['tailwindcss.com', 'v3.tailwindcss.com'], '@mui/material': ['mui.com'], '@dcloudio/uni-app': ['uniapp.dcloud.net.cn'],
+  'uview-plus': ['uview-plus.jiangruyi.com', 'uiadmin.net'] });

package/design-gate.mjs

@@ -2,11 +2,13 @@ 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 { assertDesignStageSources, assertDesignStageWrite } from './design-stage.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 (policy?.design) assertDesignStageWrite(policy.design, name, after);
   if (!designUiCandidate(name, before, after) && !policy?.design?.rules.uiPaths.includes(name)) return null;
   assertDesignDeclaration(policy, [name]);
   const design = validateDesignPolicy(policy?.design);
@@ -14,6 +16,7 @@ export async function assertDesignWrite(input, pass, name, before = '', after =
     || !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);
+  await assertDesignStageSources(input, design);
   assertDesignLint(design, name, before, after, await designOriginalSource(design, name));
   return { baselineDigest: design.baselineDigest, lint: 'passed' };
 }

package/design-operations.mjs

@@ -9,6 +9,7 @@ import { fetchDesignReference, frameworkBinding, FRAMEWORK_DOC_HOSTS, assertFroz
 import { assertDesignDeclaration } from './design-gate.mjs';
 import { verifyDesignBrowser } from './design-browser.mjs';
 import { readDesignBrowserIdentity } from './design-browser-identity.mjs';
+import { assertDesignStageSources, designAcceptanceScope } from './design-stage.mjs';
 
 export async function recordDesignFlow(input) {
   const site = validateDesignSite(input.site), directory = await designDirectory(input), diagram = designMermaid(site);
@@ -55,13 +56,15 @@ export async function proposeDesign(input) {
     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 assertDesignStageSources(input, design);
   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'),
+    acceptanceScope: designAcceptanceScope(design),
     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.' };
+    instruction: 'Show the whole-site flow, reference links, generated images and exact component/token/interaction rules to the user. For a stage, explicitly show its executable pages/edges and hashed read-only context; do not claim whole-site acceptance. 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 = {};

package/design-policy.mjs

@@ -1,6 +1,7 @@
 import { canonical, sha256 } from './local-integrity.mjs';
 import { designSchema } from './design-contracts.mjs';
 import { FRAMEWORK_DOC_HOSTS } from './design-frameworks.mjs';
+import { validateDesignStage, executableDesignPages, executableDesignEdges, validateDesignHandoffs } from './design-stage.mjs';
 
 export function designFail(code, message) { throw Object.assign(new Error(message), { code: `ENTROROVE_DESIGN_${code}` }); }
 export const designDigest = value => sha256(canonical(value));
@@ -38,7 +39,9 @@ function validateDesignSources(policy) {
     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');
+  if (new Set(policy.frameworks.map(framework => canonical([framework.packagePath, framework.packageName]))).size !== policy.frameworks.length) {
+    designFail('FRAMEWORK', 'Each actual package file must declare one unambiguous locked version per framework');
+  }
   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');
 }
@@ -47,6 +50,7 @@ export function validateDesignPolicy(raw) {
   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);
+  validateDesignStage(policy);
   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');
@@ -67,7 +71,7 @@ export function validateDesignPolicy(raw) {
     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']) {
+  for (const page of site.pages.filter(page => executableDesignPages(policy).includes(page.id))) 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);
@@ -80,6 +84,7 @@ function validateDesignScenarios(policy) {
     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');
+    if (rules.stage && !executableDesignPages(policy).includes(page.id) && scenario.steps.length) designFail('STAGE', 'Read-only context scenarios cannot execute interactions');
     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) {
@@ -91,14 +96,17 @@ function validateDesignScenarios(policy) {
     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');
+      if (!executableDesignEdges(policy).includes(edge.id)) designFail('STAGE', 'This interaction belongs to a later stage and cannot execute now');
       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);
+      validateDesignHandoffs(step, edge);
     }
     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');
+  const required = mockups.map((mockup, index) => ({ mockup, index })).filter(({ mockup }) => executableDesignPages(policy).includes(mockup.pageId));
+  if (required.some(({ index }) => !used.has(index)) || executableDesignEdges(policy).some(id => !edges.has(id))) designFail('COVERAGE', 'Browser scenarios must cover every executable mockup and original interaction in this approved acceptance scope');
 }
 function validateReadBack(step, edge, page, policy) {
   const proof = step.readBack;
@@ -128,7 +136,7 @@ export function validateDesignReport(raw, policy) {
     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');
+      || result.stateChecks !== scenario.steps.filter(step => step.readBack || step.storageHandoffs?.length).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

package/design-release.mjs

@@ -1,6 +1,7 @@
 export const DESIGN_GATE_SOURCE_FILES = [
   "design-browser-checks.mjs",
   "design-browser-identity.mjs",
+  "design-browser-pages.mjs",
   "design-browser-state.mjs",
   "design-browser.mjs",
   "design-context.mjs",
@@ -15,10 +16,15 @@ export const DESIGN_GATE_SOURCE_FILES = [
   "design-policy.d.mts",
   "design-policy.mjs",
   "design-research.mjs",
+  "design-research-network.mjs",
   "design-runner.mjs",
   "design-store.mjs",
+  "design-stage.mjs",
+  "design-stage-contracts.mjs",
+  "design-storage.mjs",
   "design-ui.mjs",
   "DESIGN-GATES.md",
+  "DESIGN-STAGED-ACCEPTANCE.md",
   "design-release.mjs"
 ];
 export const designGateReleaseLabels = Object.fromEntries(DESIGN_GATE_SOURCE_FILES.map(file => [file,

package/design-research-network.mjs

@@ -0,0 +1,82 @@
+import https from 'node:https';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import { designFail } from './design-policy.mjs';
+
+export function publicResearchIp(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);
+}
+const timeoutError = () => Object.assign(new Error('Research fetch timed out'), { code: 'ENTROROVE_DESIGN_RESEARCH_TIMEOUT' });
+export function researchResponse(url, addresses, { accept = 'text/html,text/plain,application/json', maximumBytes = 2_097_152 } = {}) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let bytes = 0, request, settled = false;
+    const fail = error => { if (!settled) { settled = true; clearTimeout(timer); reject(error); request?.destroy(error); } };
+    const timer = setTimeout(() => fail(timeoutError()), 15_000);
+    try {
+      request = https.get(url, { agent: false, rejectUnauthorized: true, headers: { accept, 'user-agent': 'Entrorove design research' },
+        lookup: (_host, options, callback) => callback(null, options.all ? [addresses[0]] : addresses[0].address, 4) }, response => {
+        response.on('data', chunk => {
+          bytes += chunk.length;
+          if (bytes > maximumBytes) fail(Object.assign(new Error('Research response exceeds its bounded size'), { code: 'ENTROROVE_DESIGN_RESEARCH_SIZE' }));
+          else chunks.push(chunk);
+        });
+        response.on('end', () => {
+          if (settled) return;
+          settled = true; clearTimeout(timer);
+          resolve({ status: response.statusCode, location: response.headers.location, type: response.headers['content-type'], body: Buffer.concat(chunks) });
+        });
+        response.on('aborted', () => fail(Object.assign(new Error('Research response was interrupted'), { code: 'ENTROROVE_DESIGN_RESEARCH_HTTP' })));
+        response.on('error', fail);
+      });
+      request.setTimeout(15_000, () => fail(timeoutError())); request.on('error', fail);
+    } catch (error) { fail(error); }
+  });
+}
+const dnsName = value => typeof value === 'string' ? value.toLowerCase().replace(/\.$/, '') : '';
+function publicDnsAnswers(result, hostname) {
+  let body; try { body = JSON.parse(result.body.toString('utf8')); } catch { designFail('RESEARCH_DNS', 'Public DNS returned invalid JSON'); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) designFail('RESEARCH_DNS', 'Public DNS returned an invalid response object');
+  const name = dnsName(hostname), answers = body.Answer;
+  if (result.status !== 200 || !/^application\/(dns-json|json)\b/i.test(result.type ?? '')
+    || body.Status !== 0 || body.TC === true || body.CD === true || !Array.isArray(body.Question) || body.Question.length !== 1
+    || body.Question[0]?.type !== 1 || dnsName(body.Question[0]?.name) !== name
+    || !Array.isArray(answers) || !answers.length || answers.length > 128
+    || answers.some(item => !item || ![1, 5].includes(item.type) || typeof item.name !== 'string' || typeof item.data !== 'string')) {
+    designFail('RESEARCH_DNS', 'Public DNS did not return its exact complete original question');
+  }
+  const names = new Set([name]); let current = name;
+  for (let depth = 0; depth < 16; depth++) {
+    const aliases = answers.filter(item => item.type === 5 && dnsName(item.name) === current);
+    if (!aliases.length) break;
+    const alias = dnsName(aliases[0].data);
+    if (aliases.length !== 1 || !alias || alias.length > 253 || net.isIP(alias) || names.has(alias)
+      || alias.split('.').some(part => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(part))) designFail('RESEARCH_DNS', 'Public DNS returned an invalid alias chain');
+    names.add(alias); current = alias;
+    if (depth === 15) designFail('RESEARCH_DNS', 'Public DNS alias chain exceeds its bound');
+  }
+  if (answers.some(item => item.type === 1 && !publicResearchIp(item.data))) designFail('RESEARCH_URL', 'Research hostname resolves outside the public internet');
+  const addresses = answers.filter(item => item.type === 1 && names.has(dnsName(item.name)))
+    .map(item => ({ address: item.data, family: 4 }));
+  if (!addresses.length) designFail('RESEARCH_DNS', 'Public DNS has no bound public IPv4 address');
+  return addresses;
+}
+export async function publicResearchAddresses(hostname) {
+  let timer;
+  const addresses = await Promise.race([dns.lookup(hostname, { all: true, family: 4 }),
+    new Promise((_resolve, reject) => { timer = setTimeout(() => reject(timeoutError()), 15_000); })]).finally(() => clearTimeout(timer));
+  if (addresses.length && addresses.every(item => publicResearchIp(item.address))) return addresses;
+  // Some local DNS proxies return RFC2544 virtual addresses. Never connect to
+  // them: obtain real answers over certificate-validated HTTPS at a fixed public
+  // resolver IP, validate every A record, then pin the documentation connection.
+  if (!addresses.length || !addresses.every(item => net.isIP(item.address) === 4 && /^198\.(18|19)\./.test(item.address))) {
+    designFail('RESEARCH_URL', 'Research hostname resolves outside the public internet');
+  }
+  const resolver = new URL('https://1.1.1.1/dns-query'); resolver.searchParams.set('name', hostname); resolver.searchParams.set('type', 'A');
+  const result = await researchResponse(resolver, [{ address: '1.1.1.1', family: 4 }], { accept: 'application/dns-json', maximumBytes: 65_536 });
+  return publicDnsAnswers(result, hostname);
+}

package/design-research.mjs

@@ -1,43 +1,23 @@
-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 { publicResearchAddresses, researchResponse } from './design-research-network.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)
+    || net.isIP(url.hostname.replace(/^\[|\]$/g, '')) || /(^|\.)(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);
-  });
+  const url = researchUrl(value), addresses = await publicResearchAddresses(url.hostname);
+  const result = await researchResponse(url, addresses);
   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);
@@ -76,7 +56,10 @@ export async function assertDeclaredDesignFrameworks(input, design) {
         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');
+          if (Object.keys(packages).some(packageName => Object.hasOwn(FRAMEWORK_DOC_HOSTS, packageName)
+            && !design.frameworks.some(framework => framework.packageName === packageName && framework.packagePath === name))) {
+            designFail('FRAMEWORK_MISSING', 'Research every actual declared framework in its nearest UI package using that package file and locked version');
+          }
           checked.add(name);
         }
         break;

package/design-runner.mjs

@@ -3,10 +3,12 @@ import { assertDesignDeclaration } from './design-declaration.mjs';
 import { assertDesignWrite } from './design-gate.mjs';
 import { designUiCandidate } from './design-ui.mjs';
 import { designFail } from './design-policy.mjs';
+import { assertDesignStageSources } from './design-stage.mjs';
 
 export async function designRunnerBefore(input, authority) {
   const policy = authority.plan.policy.discipline, originals = new Map();
   if (!policy || policy.access === 'read-only') return originals;
+  if (policy.design) await assertDesignStageSources(input, policy.design);
   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);
@@ -19,6 +21,7 @@ export async function designRunnerBefore(input, authority) {
 }
 export async function designRunnerAfter(input, authority, changed, originals) {
   const policy = authority.plan.policy.discipline;
+  if (policy?.design) await assertDesignStageSources(input, policy.design);
   for (const name of changed) {
     const target = await mutationTarget14(authority.root, name, true);
     const source = target.exists && target.stat.size <= 2_097_152

package/design-stage-contracts.mjs

@@ -0,0 +1,12 @@
+import { object, array, text, identifier, relativePath, sha256 } from './local-contract-types.mjs';
+
+const names = min => ({ ...array(identifier, min), maxItems: 256, uniqueItems: true });
+const source = object({ path: relativePath, sha256 }, ['path', 'sha256']);
+export const DESIGN_STAGE_SCHEMA = object({ id: identifier, requirementIds: names(1), pageIds: names(1), edgeIds: names(0),
+  readOnlyPages: { ...array(object({ pageId: identifier, sources: { ...array(source, 1), maxItems: 128 } }, ['pageId', 'sources']), 0), maxItems: 128 } },
+['id', 'requirementIds', 'pageIds', 'edgeIds', 'readOnlyPages']);
+const value = { anyOf: [{ type: 'string', maxLength: 8192 }, { type: 'null' }] };
+export const DESIGN_HANDOFF_SCHEMA = object({ area: { enum: ['local-storage', 'session-storage'] },
+  key: { ...text, maxLength: 128, pattern: '^[^\\u0000-\\u001f\\u007f]+$' },
+  method: { enum: ['setItem', 'removeItem'] }, before: value, after: value, count: { const: 1 } },
+['area', 'key', 'method', 'before', 'after', 'count']);