@antprofuse/saddle-islands-tools 0.1.13 → 0.1.14

package/package.json

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

package/tools/docs/minifish-testing.md

@@ -102,3 +102,11 @@ MT使用 `iteration stage-gate` 时必须提供 `--compile-result NEW_EXTERNAL_D
 
 
 分支未出现与组件本身隐藏必须区分。仅检查分支是否出现时使用 `{kind:"component-state", target:"cmp_123abc", componentState:"源分支名", present:false}`；同一组件可处于另一个正式状态而保持可见。公共工具观察唯一组件、实际状态和可见性，未知或缺失状态不能冒充“该分支不存在”。`present:true` 验证当前可见分支。它仍是原case内的断言，不新增平行case；分支内部的具体组件及内容继续独立断言。
+
+### 页面视觉（非组件身份）
+
+`kind: "page-visual"` 保留页面视觉责任，不声明 `target`、`instance` 或组件状态，不进入cmp覆盖计数。期望支持 `fullWidth: true`、`fullHeight: true`、`noHorizontalOverflow: true`、`backgroundColor: "rgb(...)"`，至少声明一项；暂不支持按住阶段。尺寸是业务页视口的完整宽高（含起点），不是宿主壳或某个组件的尺寸。
+
+Owner在项目配置填写 `pageSourceId`，精确引用冻结 `anchorInventory` 中 `kind: page` 的源ID；与已有 `pageRoute` 一并绑定到编译产物。公共编译拒绝未知页面、缺绑定及借用组件身份，执行前拒绝与冻结绑定不同的运行路由。
+
+产品在业务页面唯一根节点声明 `data-page-root="true"`，它是布尔页面载体标记，不是组件ID，不加入 `.registry`。工具在已选择的业务frame内采集该根节点，Minifish原生 `$$dataset.pageRoot` 优先；缺失、重复或非法标记失败。不按期望颜色、尺寸、CSS类猜选根节点。背景取该实际根的计算值，水平溢出同时检查该根和业务文档；运行证据保留源页面绑定与实际几何。测试阶段静态验证声明和绑定，实际渲染结果由产品阶段验证。

package/tools/modules/minifish/compiler/anchor-coverage.mjs

@@ -1,3 +1,4 @@
+import {validatePageVisual} from '../harness/page-visual.mjs';
 import {validateSpatial} from '../harness/spatial-contract.mjs';
 import assert from 'node:assert/strict';
 
@@ -16,6 +17,7 @@ export function assertionComponents(plan){
  const seen=new Set(),components=new Set();
  for(const a of plan.assertions){
   assert(a&&typeof a.id==='string'&&a.id&&!seen.has(a.id),'Unique assertion identity required');seen.add(a.id);
+  if(a.kind==='page-visual'){validatePageVisual(a);assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
   if(a.spatial!==undefined){
    assert(a.kind==='region'&&(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Spatial snapshot currently requires held region assertion');
    validateSpatial(a.spatial);

package/tools/modules/minifish/compiler/component-contract.mjs

@@ -30,8 +30,14 @@ export async function loadComponentContract(project){
  const inventory=await read(sourcePath);assert.equal(inventory.sha256,source.sha256,'Inventory digest mismatch');
  const registry=path.resolve(root,'../.registry');
  const active=await read(path.join(registry,'anchors.jsonc')),retired=await read(path.join(registry,'anchors-retired.jsonc'));
+ const parsedInventory=JSON.parse(inventory.bytes);let page;
+ if(config.pageSourceId!==undefined){
+  assert(typeof config.pageSourceId==='string'&&parsedInventory.targets.some(row=>row.kind==='page'&&row.id===config.pageSourceId),'Configured page must be an exact frozen source page');
+  assert(typeof config.pageRoute==='string'&&config.pageRoute,'Configured product route required');
+  page={sourceId:config.pageSourceId,route:config.pageRoute};
+ }
  const {activeComponentIds,componentStates,branches}=JSON.parse(execFileSync('python3',[fileURLToPath(new URL('../component_index_bridge.py',import.meta.url))],{input:JSON.stringify({inventory:JSON.parse(inventory.bytes),active:active.bytes.toString(),retired:retired.bytes.toString(),withStates:true}),encoding:'utf8',env:{...process.env,PYTHONDONTWRITEBYTECODE:'1'}}));
  assert.equal(git('rev-parse','HEAD'),head,'Candidate changed during contract construction');
  const binding=x=>({path:x.path,sha256:x.sha256});
- return {schemaVersion:1,head,activeComponentIds,componentStates,branches,config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
+ return {schemaVersion:1,head,activeComponentIds,componentStates,branches,...(page?{page}:{}),config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
 }

package/tools/modules/minifish/harness/component-state.mjs

@@ -1,3 +1,4 @@
+import {validatePageVisual} from './page-visual.mjs';
 import assert from 'node:assert/strict';
 
 // Serialized independently; the product declaration is observed, never inferred
@@ -18,6 +19,7 @@ export function validateComponentStates(plan,contract){
  const reference=ref=>{if(ref?.target!==undefined)assert(active.has(ref.target),'Reference must belong to the frozen active component set');};
  for(const actions of [plan.actions,plan.beforeTarget,plan.afterTarget,plan.completion])for(const action of actions??[])reference(action);
  for(const a of plan.assertions??[]){
+  if(a.kind==='page-visual'){validatePageVisual(a);assert(contract.page?.sourceId&&contract.page.route,'Compiler-bound page required');assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
   reference(a);
   for(const ref of [...(a.spatial?.absent??[]),...(a.spatial?.order??[]).flatMap(pair=>[pair.above,pair.below])])reference(ref);
   if(a.kind==='component-state')assert(a.componentState!==undefined,'Branch state required');

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

@@ -1,3 +1,4 @@
+import {observePageVisual,assertPageRoute} from './page-visual.mjs';
 import {sampleComponentState,assertComponentState,assertComponentBranch,validateComponentStates} from './component-state.mjs';
 import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
 import {prepareHeldWithSpatial} from './held-spatial.mjs';
@@ -32,6 +33,7 @@ function target(root, name) { return semanticLocator(root, name); }
 export async function runMiniappCase({page, plan, testInfo}) {
   validateRegionVisualAssertions(plan.assertions);
   validateComponentStates(plan,plan.componentContract);
+  if(plan.assertions.some(a=>a.kind==='page-visual'))assertPageRoute(plan.componentContract.page,process.env.MINIFISH_PAGE_ROUTE);
   assert(plan.componentContract?.schemaVersion===1,'Compiler-bound component membership contract required');
   validateComponentMembership({declarations:[]},plan.componentContract.activeComponentIds);
   assert.equal(plan.resources.length, 0, 'resource handling is not implemented in this runner yet');
@@ -120,11 +122,12 @@ export async function runMiniappCase({page, plan, testInfo}) {
       if(!held.timing.eligible){result.inputValidity='invalid';result.target='invalidated';}
     }else for (const assertion of plan.assertions) {
       await synchronizeAnchors(app.root);
-      const locator=assertion.kind==='host-navigation'?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
+      const locator=['host-navigation','page-visual'].includes(assertion.kind)?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
       try {
         result.observations.componentMembership=validateComponentMembership(await app.root.locator(':root').evaluate(sampleDeclaredComponents),plan.componentContract.activeComponentIds);
         if(assertion.componentState!==undefined&&assertion.kind!=='component-state'){await expect(locator).toHaveCount(1);await expect(locator).toBeVisible();result.observations[assertion.id+':componentState']=assertComponentState(await locator.evaluate(sampleComponentState),assertion.componentState);}
-        if(assertion.kind==='component-state'){
+        if(assertion.kind==='page-visual'){result.observations[assertion.id]=await observePageVisual(app.root,assertion,plan.componentContract.page);
+        }else if(assertion.kind==='component-state'){
           const count=await locator.count(),members=[];assert(count<=1,'Unique branch owner required');
           if(count)members.push({componentState:await locator.evaluate(sampleComponentState),visible:await locator.isVisible()});
           result.observations[assertion.id]=assertComponentBranch({count,members},assertion.componentState,assertion.present,plan.componentContract.componentStates[assertion.target]);

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

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+const fields=new Set(['fullWidth','fullHeight','noHorizontalOverflow','backgroundColor']);
+export function validatePageVisual(a){
+ assert(a.kind==='page-visual','Page visual kind required');
+ assert(a.target===undefined&&a.instance===undefined&&a.componentState===undefined&&a.spatial===undefined&&a.visual===undefined,'Page observation cannot impersonate a component');
+ let checks=0;
+ for(const key of fields){
+  if(a[key]===undefined)continue;
+  if(key==='backgroundColor')assert(typeof a[key]==='string'&&a[key].trim(),'Page background must be explicit');
+  else assert(a[key]===true,'Page geometry flags must assert true');
+  checks++;
+ }
+ assert(checks>0,'Substantive page visual expectation required');
+}
+// Runs only in the selected business frame. The page marker is not a component ID.
+export function sampleBusinessPage(root){
+ const doc=root.ownerDocument;
+ const candidates=[];
+ for(const n of doc.querySelectorAll('*')){
+  const native=Object.prototype.hasOwnProperty.call(n,'$$dataset');
+  const declared=native?!!n.$$dataset&&Object.prototype.hasOwnProperty.call(n.$$dataset,'pageRoot'):n.hasAttribute('data-page-root');
+  if(!declared)continue;
+  const value=native?n.$$dataset.pageRoot:n.getAttribute('data-page-root');
+  if(value!==true&&value!=='true')throw Error('Invalid business page marker');
+  candidates.push(n);
+ }
+ if(candidates.length!==1)throw Error('Exactly one declared business page root required');
+ const node=candidates[0],box=node.getBoundingClientRect(),style=doc.defaultView.getComputedStyle(node);
+ let visible=box.width>0&&box.height>0;
+ for(let n=node;n;n=n.parentElement){const s=doc.defaultView.getComputedStyle(n);visible&&=s.display!=='none'&&s.visibility==='visible'&&Number(s.opacity)>0;}
+ return {box:{x:box.x,y:box.y,width:box.width,height:box.height},viewport:{width:doc.defaultView.innerWidth,height:doc.defaultView.innerHeight},
+  visible,backgroundColor:style.backgroundColor,scrollWidth:node.scrollWidth,clientWidth:node.clientWidth,
+  documentScrollWidth:doc.documentElement.scrollWidth,frame:doc.defaultView.location.href};
+}
+export function assertPageVisual(metrics,a){
+ validatePageVisual(a);
+ assert(metrics?.visible,'Business page must be visible');
+ for(const value of [metrics.box?.x,metrics.box?.y,metrics.box?.width,metrics.box?.height,metrics.viewport?.width,metrics.viewport?.height])assert(Number.isFinite(value),'Finite page geometry required');
+ assert(metrics.viewport.width>0&&metrics.viewport.height>0&&metrics.box.width>0&&metrics.box.height>0,'Nonzero business page geometry required');
+ const near=(x,y,name)=>assert(Math.abs(x-y)<=.25,name);
+ if(a.fullWidth){near(metrics.box.x,0,'Page starts at viewport left');near(metrics.box.width,metrics.viewport.width,'Page full width');}
+ if(a.fullHeight){near(metrics.box.y,0,'Page starts at viewport top');near(metrics.box.height,metrics.viewport.height,'Page full height');}
+ if(a.noHorizontalOverflow){assert(Number.isFinite(metrics.scrollWidth)&&Number.isFinite(metrics.clientWidth)&&Number.isFinite(metrics.documentScrollWidth),'Page overflow measurements required');assert(metrics.scrollWidth<=metrics.clientWidth&&metrics.documentScrollWidth<=metrics.viewport.width,'No horizontal business overflow');}
+ if(a.backgroundColor!==undefined)assert.equal(metrics.backgroundColor,a.backgroundColor,'Page background');
+ return {check:'page-visual',metrics};
+}
+export async function observePageVisual(root,a,contract){
+ assert(contract?.sourceId&&contract.route,'Compiler-bound page source and route required');
+ return {...assertPageVisual(await root.locator(':root').evaluate(sampleBusinessPage),a),page:contract};
+}
+
+export function assertPageRoute(contract,route){
+ assert(contract?.sourceId&&contract.route,'Compiler-bound page required');
+ assert(typeof route==='string'&&route.replace(/^\//,'')===contract.route.replace(/^\//,''),'Runtime page route differs from frozen page binding');
+}