@antprofuse/saddle-islands-tools 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-tools",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Independent Saddle–Islands engineering tools",
   "files": [
     "tools"

package/tools/docs/minifish-testing.md

@@ -30,3 +30,15 @@ Eight is the public tool default, not a universal hardware optimum. Lower concur
 Both `batch-input.json` and `batch-summary.json` contain `concurrencyPolicy`: `defaultWorkers`, `requestedWorkers`, `actualConcurrency` (effective simultaneous worker upper bound, not a measured peak), `workersReason`, and truthful `shardSizes` including plugin tails. The summary's `concurrency` uses that effective upper bound; its worker records retain every actual shard and lifecycle receipt.
 
 Legacy component-host integrations must supply an explicit `repositoryRoot` to `component_runtime.main(prepare, sourceRoot, projectRoot, repositoryRoot)`. No directory-depth inference is performed. Current case packages use the public `run` or `batch` commands.
+
+### 区域视觉声明
+
+`region` 且 `check: "visual"` 的断言由公共编译器及运行器校验。`visual-expectation.mjs` 公开 `validateVisualExpectation` 和纯函数 `assertVisualMetrics`。声明必须含正数 `designWidth` 和至少一项实际期望；空对象、仅设计宽度、未知键、非有限数值被拒绝，合法零值保留。
+
+支持 `text`（fontSize/fontWeight/color/lineHeight）、`lengths`（padding四边、margin四边、borderRadius、gap/rowGap/columnGap）、`dimensions`（width/height）、`backgroundColor`、`align`，以及 `layout`（position/display/flexDirection/alignItems/justifyContent/overflowX/overflowY/boxSizing）。数值长度以声明的设计宽度换算，字体容差0.02px，几何容差0.25px；布局与颜色按浏览器计算值比较。
+
+运行器在声明的语义载体上独立采集并判定；按压状态使用释放前冻结的原生快照。观察模块的自报成功不能替代公共判定。该合同不证明期望覆盖完整，也不为缺少语义身份的内部部件猜测选择器；这类观察能力须先明确，不能按期望尺寸或颜色挑选能通过的元素。其他断言类别不隐式套用本合同。
+
+可选 `carrier` 默认为 `semantic-root`。`source-content-group` 在语义root内对可见文字/图像取最低公共元素祖先；`owned-text-block` 在该组内要求唯一不属于其他语义目标的文字分支。选择与期待样式、class、原型HTML标签无关，候选缺失或歧义明确失败；不适用的拓扑不得借此猜测观察目标。`viewportInsets` 可声明 left/right/top/bottom 到业务frame视口的设计长度，返回采样记录包含原root盒及是否选中root。
+
+按压快照目前只支持 `semantic-root`，其他carrier在按下前拒绝，不能释放后采样冒充按住状态。这是明确能力限制，不能默默降级。内容分组不覆盖背景装饰/无文字无图像部件或Shadow DOM；相应责任另用适用的公开观察合同。

package/tools/modules/minifish/checks/package.test.mjs

@@ -17,7 +17,7 @@ async function fixture(){
  await writeFile(path.join(project,'harness/regions/alternate.mjs'),"import {semanticLocator} from '@antprofuse/saddle-islands-tools/tools/modules/minifish/harness/semantic-anchor.mjs';export function locate(root,name){return semanticLocator(root,name)};export function assertTarget(){}");
  return {root,project,configFile,config,loaded:await loadProject(project,configFile)};
 }
-test('alternate project static closure records tool/adapter separately and copies no unrelated region',async()=>{const f=await fixture();try{const output=path.join(f.root,'artifact'),records=await packageRunner(f.loaded,output,'regions/alternate.mjs');assert(records.some(r=>r.kind==='tool'&&r.path==='harness/semantic-anchor.mjs'));assert(records.some(r=>r.kind==='adapter'&&r.path==='harness/regions/alternate.mjs'));assert(records.every(r=>/^[a-f0-9]{64}$/.test(r.sha256)));assert(!records.some(r=>r.path.includes('T1')));assert((await readFile(path.join(output,'adapters/harness/regions/alternate.mjs'),'utf8')).includes('../../../tools/harness/semantic-anchor.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
+test('alternate project static closure records tool/adapter separately and copies no unrelated region',async()=>{const f=await fixture();try{const output=path.join(f.root,'artifact'),records=await packageRunner(f.loaded,output,'regions/alternate.mjs');assert(records.some(r=>r.kind==='tool'&&r.path==='harness/semantic-anchor.mjs'));for(const name of ['visual-expectation.mjs','visual-carrier.mjs']){assert(records.some(r=>r.kind==='tool'&&r.path==='harness/'+name));assert((await readFile(path.join(output,'tools/harness',name),'utf8')).length>0);}assert(records.some(r=>r.kind==='adapter'&&r.path==='harness/regions/alternate.mjs'));assert(records.every(r=>/^[a-f0-9]{64}$/.test(r.sha256)));assert(!records.some(r=>r.path.includes('T1')));assert((await readFile(path.join(output,'adapters/harness/regions/alternate.mjs'),'utf8')).includes('../../../tools/harness/semantic-anchor.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
 for(const [name,code] of [['unknown package',"import 'fs';"],['dependency traversal',"import '../../outside.mjs';"],['direct DOM',"export const read=root=>root.evaluate(()=>1);"],['dynamic import',"export const read=()=>import('./other.mjs');"]])test(name+' is rejected from the closed observation dependency graph',async()=>{const f=await fixture();try{await writeFile(path.join(f.project,'harness/regions/alternate.mjs'),code);await writeFile(path.join(f.project,'outside.mjs'),'export const leaked=true;');await assert.rejects(packageRunner(f.loaded,path.join(f.root,'artifact'),'regions/alternate.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
 test('symlink aliases, undeclared module, missing config, and package output are rejected',async()=>{const f=await fixture();try{const module=path.join(f.project,'harness/regions/alternate.mjs');await rm(module);await writeFile(path.join(f.project,'harness/other.mjs'),'export const safe=true;');await symlink('../other.mjs',module);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'alias'),'regions/alternate.mjs'),/Symlink/);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'unknown'),'regions/unknown.mjs'),/declared module/);await assert.rejects(loadProject(f.project,path.join(f.project,'missing.json')));await assert.rejects(packageRunner(f.loaded,path.join(f.project,'artifact'),'regions/alternate.mjs'),/outside/);}finally{await rm(f.root,{recursive:true,force:true});}});
 test('generic composition preserves exact preparation and original ID mappings without project names',()=>{const noop=()=>{},policy={validateSemanticTargets:noop,supplementalDefinition:()=>null,officialTitle:()=>false,validatePreparationOverrides:noop,validateFixtureTypes:noop,validateSpecialBoundaries:noop,validateIndependentFixture:noop,validatePacketPlan:noop,validatePluginEvents:noop,validatePluginAssertionIdentity:noop,validateObservationModuleName:noop};const catalog={cases:[{id:'alternate / page / value / content',title:'value'}]},definition={caseId:catalog.cases[0].id,ancestors:['open'],basis:[{path:'alternate/source.yaml'}],preparation:{},assertions:[{id:'value',kind:'text',target:'alternate / page / value',expected:'42',count:1}]},fragment={id:'open',inputs:{query:{key:'42'}},boundaries:[],actions:[{kind:'open-page'}]};const plan=compileCase(catalog,definition,[fragment],policy);assert.deepEqual(plan.inputs,fragment.inputs);assert.deepEqual(plan.assertions,definition.assertions);assert.equal(plan.case.id,definition.caseId);assert.throws(()=>compileCase(catalog,{...definition,ancestors:['unknown']},[fragment],policy),/missing preparation/);});

package/tools/modules/minifish/compiler/case-plan.mjs

@@ -1,3 +1,4 @@
+import {validateRegionVisualAssertions} from '../harness/visual-expectation.mjs';
 import assert from 'node:assert/strict';
 import {validateTargetActions} from '../harness/target-actions.mjs';
 function jsonValue(value, path = '$') {
@@ -34,6 +35,7 @@ export function compileCase(catalog, definition, fragments,policy) {
   assert(policy&&typeof policy.validateSemanticTargets==='function','Explicit project plan policy required');
   const {validateSemanticTargets,validateIndependentFixture,validatePacketPlan,validatePluginEvents,validatePluginAssertionIdentity,validateObservationModuleName}=policy;
   jsonValue(definition);
+  validateRegionVisualAssertions(definition.assertions);
   validateSemanticTargets(definition);
   jsonValue(fragments);
   for(const fragment of fragments)validateSemanticTargets(fragment);
@@ -170,6 +172,7 @@ export function compileCase(catalog, definition, fragments,policy) {
 export function renderCaseModule(plan,validateSemanticTargets) {
   assert.equal(typeof validateSemanticTargets,'function','Explicit project source validator required');
   jsonValue(plan);
+  validateRegionVisualAssertions(plan.assertions);
   validateSemanticTargets(plan);
   return `// Generated from miniapp case definitions. Do not edit.\nexport default ${JSON.stringify(plan, null, 2)};\n`;
 }

package/tools/modules/minifish/harness/held-snapshot.mjs

@@ -1,3 +1,4 @@
+import {assertVisualMetrics} from './visual-expectation.mjs';
 import assert from 'node:assert/strict';
 import {sampleNativeMetrics,sampleNativeTextVisibility,sampleNativeStyle,sampleNativePressed,sampleHeldNativeState} from './native-dom-sampling.mjs';
 import {nativeMetricsFrameIdentity} from './independent-visual.mjs';
@@ -53,6 +54,7 @@ export function validateFrozenHeldAssertion(snapshot,a,validators){
  for(const member of group.members){assert(matchesNativeSemanticIdentity(member.identity,a.target,a.instance),'Original semantic identity and optional instance must match');// Preserve measured :active; declared assertions do not require CSS :active.
 
   if(a.enabled)assert.equal(member.state.enabled,true,'Original native enabled obligation');validators.validateObservation(member.metrics,a);
+  if(a.kind==='region'&&a.check==='visual'){assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier not captured');assertVisualMetrics(member.metrics,a.visual);}
   if(a.textFits)validateNativeTextVisibility(member.textPaint,{selfOverflow:'contain'});observations.push({...member.metrics,...(a.textFits?{textPaint:member.textPaint}:{})});
  }
  return {count:group.count,visible:group.members.map(m=>m.state.visible),observations,snapshotVersion:snapshot.version,snapshotAt:snapshot.snapshotAt};

package/tools/modules/minifish/harness/independent-case-runner.mjs

@@ -1,3 +1,4 @@
+import {validateRegionVisualAssertions,assertVisualMetrics} from './visual-expectation.mjs';
 import {hostPolicy} from '@minifish/project-host';
 import {prepareHeldNativeInput,executeHeldSnapshot} from './held-snapshot.mjs';
 import {prepareHeldSnapshot,independentBoundary,assertNativeState,projectAssert,locateProject,queryBoundaryIds,validateReleasedPaymentRows} from '@minifish/project-runtime';
@@ -26,6 +27,7 @@ export const screenshotPolicyVersion = 1;
 function target(root, name) { return semanticLocator(root, name); }
 
 export async function runMiniappCase({page, plan, testInfo}) {
+  validateRegionVisualAssertions(plan.assertions);
   assert.equal(plan.resources.length, 0, 'resource handling is not implemented in this runner yet');
   const boundary = plan.boundaries.length ? independentBoundary(plan.boundaries) : zeroBusinessPlan();
   const images = installRendererImageEvidence(page);
@@ -92,6 +94,7 @@ export async function runMiniappCase({page, plan, testInfo}) {
     assert(app, 'missing real page opening');
     await trace?.attach();
     input=targetActions({page,locate:(name,instance)=>locate(app.root,name,{instance}),synchronize:()=>synchronizeAnchors(app.root),boundary,receipts:result.actions,beforePress:async()=>{if(artifactOnly)capturePreparation=await prepareMiniappCapture(page);},observeInput:async(stage,action)=>trace?.sample(stage,app.root,boundary.evidence(),action)});
+    if(heldSpec)for(const a of plan.assertions)if(a.kind==='region'&&a.check==='visual')assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier requires a supported frozen snapshot contract');
     if(heldSpec)await prepareHeldNativeInput(app.root,heldSpec,locate(app.root,heldSpec.press.target,{instance:heldSpec.press.instance}));
     for(const action of plan.beforeTarget??[]){
       if(action.kind==='leave-return'){
@@ -114,7 +117,12 @@ export async function runMiniappCase({page, plan, testInfo}) {
         if(assertion.kind==='host-native-ui'){result.observations[assertion.id]=await assertHostNativeUi(page,app,assertion);
         }else if(assertion.kind==='carousel-frame'){result.observations[assertion.id]=await observeCarousel(app.root,assertion.contract,{urls:assertion.images,records:images.records});
         }else if(assertion.kind==='host-navigation'){result.observations[assertion.id]=await assertHostNavigation(page,app,assertion,plan.hostSystemPlan);
-        }else if(assertion.kind==='region'){result.observations[assertion.id]=await observation.assertTarget({app,page,assertion,images});
+        }else if(assertion.kind==='region'){
+          result.observations[assertion.id]=await observation.assertTarget({app,page,assertion,images});
+          if(assertion.check==='visual') {
+            const metrics=await nativeMetrics(locator,{carrier:assertion.visual.carrier});
+            result.observations[assertion.id]={...result.observations[assertion.id],publicVisual:assertVisualMetrics(metrics,assertion.visual)};
+          }
         }else if(await projectAssert({root:app.root,assertion,locator,locate,images,result})){
         }else if(['hidden','visible'].includes(assertion.kind)){await assertNativeState(locator,assertion);
         }else if(assertion.kind==='text'){

package/tools/modules/minifish/harness/independent-visual.mjs

@@ -1,3 +1,4 @@
+import {resolveVisualCarrier} from './visual-carrier.mjs';
 import {sampleNativeMetrics} from './native-dom-sampling.mjs';
 import {rendererImageFrameId} from './renderer-image-evidence.mjs';
 import assert from 'node:assert/strict';
@@ -7,9 +8,9 @@ export async function nativeMetricsFrameIdentity(locator) {
  try{const frame=await handle?.ownerFrame();if(frame)frameId=rendererImageFrameId(locator.page(),frame);}finally{await handle?.dispose();}
  return frameId;
 }
-export async function nativeMetrics(locator) {
+export async function nativeMetrics(locator, {carrier='semantic-root'}={}) {
  const frameId=await nativeMetricsFrameIdentity(locator);
- const metrics=await locator.evaluate(sampleNativeMetrics);
+ const metrics=carrier==='semantic-root'?await locator.evaluate(sampleNativeMetrics):await locator.evaluate(Function('return ((root,kind)=>{const resolve='+resolveVisualCarrier.toString()+';const sample='+sampleNativeMetrics.toString()+';const selected=resolve(root,kind);return {...sample(selected),carrierEvidence:{kind,rootBox:sample(root).box,selectedIsRoot:selected===root}};})')(),carrier);
  metrics.frameId=frameId;for(const paint of [...metrics.imagePaints,...metrics.imagePaintInventory])paint.frameId=frameId;return metrics;
 }
 export function near(actual,expected,label,tolerance=.02){assert(Math.abs(actual-expected)<=tolerance,`${label}: ${actual} != ${expected}`);}

package/tools/modules/minifish/harness/native-dom-sampling.mjs

@@ -1,7 +1,7 @@
 // Existing public browser collectors, extracted without changing measured fields.
 export function sampleNativeMetrics(el){
   const s=getComputedStyle(el),r=el.getBoundingClientRect();
-  const styles=Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color','backgroundColor','borderRadius','paddingLeft','paddingRight','paddingTop','paddingBottom','marginTop','marginBottom','marginLeft','marginRight','backgroundImage','backgroundSize','backgroundRepeat','backgroundPosition','objectFit'].map(k=>[k,s[k]]));
+  const styles=Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color','backgroundColor','borderRadius','paddingLeft','paddingRight','paddingTop','paddingBottom','marginTop','marginBottom','marginLeft','marginRight','backgroundImage','backgroundSize','backgroundRepeat','backgroundPosition','objectFit','textAlign','position','display','flexDirection','alignItems','justifyContent','overflowX','overflowY','boxSizing','gap','rowGap','columnGap'].map(k=>[k,s[k]]));
   const texts=[],textStyles=[];
   function visit(node){if(node.nodeType===3 && node.textContent.trim()){const range=document.createRange();range.selectNodeContents(node);const ts=getComputedStyle(node.parentElement);textStyles.push(Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color'].map(k=>[k,ts[k]])));for(const b of range.getClientRects())if(b.width&&b.height)texts.push({x:b.x,y:b.y,width:b.width,height:b.height});}else{for(const c of node.childNodes)visit(c);if(node.shadowRoot)visit(node.shadowRoot);}}
   visit(el);

package/tools/modules/minifish/harness/visual-carrier.mjs

@@ -0,0 +1,44 @@
+/** Browser-side, expectation-independent selection inside one semantic root. */
+export function resolveVisualCarrier(root, kind = 'semantic-root') {
+  if(kind==='semantic-root')return root;
+  if(!['source-content-group','owned-text-block'].includes(kind))throw Error('Unsupported visual carrier');
+  const visible=element=>{
+    for(let p=element;p;p=p.parentElement){const s=getComputedStyle(p);if(s.display==='none'||s.visibility!=='visible'||Number(s.opacity)===0)return false;}
+    return true;
+  };
+  const content=[],texts=[];
+  const walk=node=>{
+    if(node.nodeType===3&&node.textContent.trim()&&visible(node.parentElement)) {
+      const range=node.ownerDocument.createRange();range.selectNodeContents(node);
+      if([...range.getClientRects()].some(r=>r.width>0&&r.height>0)){content.push(node.parentElement);texts.push(node);}
+    } else if(node.nodeType===1) {
+      if(node.shadowRoot)throw Error('Unsupported shadow content carrier topology');
+      if(node.tagName==='IMG'&&visible(node)){const r=node.getBoundingClientRect();if(r.width>0&&r.height>0)content.push(node);}
+      for(const child of node.childNodes)walk(child);
+    }
+  };
+  walk(root);
+  if(!content.length)throw Error('Content carrier requires actual painted text or image');
+  let group=content[0];
+  while(group&& !content.every(n=>group.contains(n)))group=group.parentElement;
+  if(!group||!root.contains(group))throw Error('Content group escaped semantic owner');
+  if(kind==='source-content-group')return group;
+  const branches=new Set();
+  for(const text of texts) {
+    let owned=true;
+    for(let p=text.parentElement;p&&p!==root;p=p.parentElement){
+      const path=p.$$dataset?.anchorId??p.getAttribute('data-anchor-id');
+      if(path){owned=false;break;}
+    }
+    if(!owned)continue;
+    let branch=text.parentElement;
+    if(branch===group)throw Error('Owned text has no distinct block');
+    while(branch.parentElement!==group)branch=branch.parentElement;
+    branches.add(branch);
+  }
+  if(branches.size!==1)throw Error('Owned text block missing or ambiguous');
+  const block=[...branches][0];
+  // Do not let an unanchored wrapper make text belonging to other targets owned.
+  for(const n of block.querySelectorAll('*'))if(n.$$dataset?.anchorId||n.getAttribute('data-anchor-id'))throw Error('Owned text block contains another semantic target');
+  return block;
+}

package/tools/modules/minifish/harness/visual-expectation.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+
+const lengths = new Set(['paddingLeft','paddingRight','paddingTop','paddingBottom','marginLeft','marginRight','marginTop','marginBottom','borderRadius','gap','rowGap','columnGap']);
+const layout = new Set(['position','display','flexDirection','alignItems','justifyContent','overflowX','overflowY','boxSizing']);
+const top = new Set(['designWidth','text','lengths','dimensions','backgroundColor','align','layout','carrier','viewportInsets']);
+function object(value, name) {
+  assert(value && Object.getPrototypeOf(value) === Object.prototype, `${name}: object required`);
+}
+function number(value, name) { assert(typeof value === 'number' && Number.isFinite(value), `${name}: finite number required`); }
+function string(value, name) { assert(typeof value === 'string' && value.trim(), `${name}: nonempty string required`); }
+function keys(value, allowed, name, validate) {
+  object(value,name);
+  for (const [key,item] of Object.entries(value)) {
+    assert(allowed.has(key), `${name}: unsupported ${key}`);
+    validate(item, `${name}.${key}`);
+  }
+  return Object.keys(value).length;
+}
+
+/** Validates declarations, not whether the source obligations are sufficiently covered. */
+export function validateVisualExpectation(value) {
+  object(value,'visual');
+  for (const key of Object.keys(value)) assert(top.has(key), `visual: unsupported ${key}`);
+  number(value.designWidth,'visual.designWidth');
+  assert(value.designWidth > 0,'visual.designWidth must be positive');
+  if(value.carrier!==undefined)assert(['semantic-root','source-content-group','owned-text-block'].includes(value.carrier),'visual: unsupported carrier');
+  let checks = 0;
+  if(value.viewportInsets!==undefined)checks+=keys(value.viewportInsets,new Set(['left','right','top','bottom']),'visual.viewportInsets',number);
+  if (value.text !== undefined) {
+    checks += keys(value.text,new Set(['fontSize','fontWeight','color','lineHeight']),'visual.text',(v,k)=>k.endsWith('.color')?string(v,k):number(v,k));
+  }
+  if (value.lengths !== undefined) checks += keys(value.lengths,lengths,'visual.lengths',number);
+  if (value.dimensions !== undefined) checks += keys(value.dimensions,new Set(['width','height']),'visual.dimensions',number);
+  if (value.layout !== undefined) checks += keys(value.layout,layout,'visual.layout',string);
+  for (const key of ['backgroundColor','align']) if (value[key] !== undefined) { string(value[key],`visual.${key}`); checks++; }
+  assert(checks > 0,'visual: at least one substantive expectation required');
+  return value;
+}
+
+function near(actual,expected,tolerance,label) {
+  number(actual,label);
+  assert(Math.abs(actual-expected)<=tolerance,`${label}: ${actual} != ${expected}`);
+}
+function pixels(value,label) {
+  assert(typeof value==='string' && /^-?(?:\d+(?:\.\d*)?|\.\d+)px$/.test(value),`${label}: resolved px required`);
+  return Number(value.slice(0,-2));
+}
+
+/** Pure public predicate. Metrics must be sampled from the declared semantic carrier. */
+export function assertVisualMetrics(metrics, expectation) {
+  const v=validateVisualExpectation(expectation), m=metrics;
+  assert(m?.box && m?.viewport && m?.styles,'visual: native metrics required');
+  number(m.viewport.width,'viewport.width');assert(m.viewport.width>0,'positive viewport width required');
+  number(m.box.width,'box.width');number(m.box.height,'box.height');
+  assert(m.box.width>0&&m.box.height>0,'visual: painted carrier required');
+  const unit=m.viewport.width/v.designWidth;
+  for(const [side,value] of Object.entries(v.viewportInsets??{})) {
+    const actual=side==='left'?m.box.x:side==='top'?m.box.y:side==='right'?m.viewport.width-m.box.x-m.box.width:m.viewport.height-m.box.y-m.box.height;
+    near(actual,value*unit,.25,`visual.viewportInsets.${side}`);
+  }
+  if(v.text && Object.keys(v.text).length) {
+    assert(m.texts?.length&&m.textStyles?.length,'visual: actual text paint required');
+    for(const style of m.textStyles) for(const [key,value] of Object.entries(v.text)) {
+      if(key==='color') assert.equal(style.color,value,'visual.text.color');
+      else if(key==='fontWeight') {assert(style.fontWeight!==''&&style.fontWeight!=null,'fontWeight required');assert.equal(Number(style.fontWeight),value,'visual.text.fontWeight');}
+      else near(pixels(style[key],key),value*unit,.02,`visual.text.${key}`);
+    }
+  }
+  for(const [key,value] of Object.entries(v.lengths??{})) near(pixels(m.styles[key],key),value*unit,.25,`visual.lengths.${key}`);
+  for(const [key,value] of Object.entries(v.dimensions??{})) near(m.box[key],value*unit,.25,`visual.dimensions.${key}`);
+  for(const [key,value] of Object.entries(v.layout??{})) assert.equal(m.styles[key],value,`visual.layout.${key}`);
+  if(v.backgroundColor!==undefined) assert.equal(m.styles.backgroundColor,v.backgroundColor,'visual.backgroundColor');
+  if(v.align!==undefined) assert.equal(m.styles.textAlign,v.align,'visual.align');
+  return {checks:'passed',expectation:v,metrics:m};
+}
+
+export function validateRegionVisualAssertions(assertions) {
+  for(const a of assertions??[]) if(a.kind==='region'&&a.check==='visual') validateVisualExpectation(a.visual);
+}