@antprofuse/saddle-islands-tools 0.0.0-stage → 0.1.3

package/tools/modules/minifish/harness/loading-input.mjs

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Only call after the case's original readiness checks, immediately before input.
+// Resolve the active SDK frame afresh on every poll; never dismiss its UI.
+export function validateNativeInputEvidence(e){
+ assert(e.business.visible&&e.business.hit,'Actual business-frame target or descendant must receive visible input');
+ for(const row of e.parents)assert(row.visible&&row.hit,'Every parent frame must hit the corresponding iframe');
+ return e;
+}
+export async function nativeInputEvidence(target){
+ const handle=await target.elementHandle();if(!handle)throw Error('Native input target absent');
+ try{
+  let frame=await handle.ownerFrame();if(!frame)throw Error('Business frame unavailable');
+  const business=await handle.evaluate(el=>{const r=el.getBoundingClientRect(),point={x:r.x+r.width/2,y:r.y+r.height/2};let visible=r.width>0&&r.height>0&&point.x>=0&&point.y>=0&&point.x<innerWidth&&point.y<innerHeight;for(let p=el;p;p=p.parentElement){const s=getComputedStyle(p);visible&&=s.display!=='none'&&s.visibility==='visible'&&Number(s.opacity)>0;}const hit=document.elementFromPoint(point.x,point.y);return {point,viewport:{width:innerWidth,height:innerHeight},visible,hit:!!hit&&(hit===el||el.contains(hit)),frame:location.href};});
+  const parents=[];let projection=business;
+  while(frame.parentFrame()){
+   const iframe=await frame.frameElement();try{
+    projection=await iframe.evaluate((el,child)=>{const r=el.getBoundingClientRect(),sx=r.width/el.offsetWidth,sy=r.height/el.offsetHeight;const point={x:r.x+(el.clientLeft+child.point.x*el.clientWidth/child.viewport.width)*sx,y:r.y+(el.clientTop+child.point.y*el.clientHeight/child.viewport.height)*sy};let visible=Number.isFinite(point.x)&&Number.isFinite(point.y)&&r.width>0&&r.height>0&&point.x>=0&&point.y>=0&&point.x<innerWidth&&point.y<innerHeight;for(let p=el;p;p=p.parentElement){const s=getComputedStyle(p);visible&&=s.display!=='none'&&s.visibility==='visible'&&Number(s.opacity)>0;}return {point,viewport:{width:innerWidth,height:innerHeight},visible,hit:document.elementFromPoint(point.x,point.y)===el,frame:location.href};},projection);
+    parents.push(projection);
+   }finally{await iframe.dispose();}
+   frame=frame.parentFrame();
+  }
+  return {business,parents};
+ }finally{await handle.dispose();}
+}
+export async function waitForNativeInput(page,target,{timeout=5000}={}) {
+ await expect.poll(async()=>{
+  try{validateNativeInputEvidence(await nativeInputEvidence(target));return 'ready';}
+  catch(error){return error.message;}
+ },{timeout,intervals:[16,32,64,100],message:'Native input must hit target in business frame and its iframe in every parent frame'}).toBe('ready');
+ const out=process.env.MINIFISH_LOADING_DIAGNOSTICS_DIR;
+ if(out){
+  const binding='nativeInput'+crypto.randomUUID().replaceAll('-','');
+  await fs.mkdir(out,{recursive:true});
+  await page.exposeBinding(binding,async(source,event)=>{
+   await fs.appendFile(path.join(out,'native-input-events.jsonl'),JSON.stringify({...event,frame:source.frame.url()})+'\n');
+  });
+  await target.evaluate((node,binding)=>{
+   for(const type of ['pointerdown','mousedown','click','dblclick']){
+    const observe=event=>{
+     if(!node.contains(event.target))return;
+     window[binding]({at:Date.now(),type,trusted:event.isTrusted,target:event.target?.outerHTML?.slice(0,800),x:event.clientX,y:event.clientY});
+    };
+    window.addEventListener(type,observe,{capture:true});
+   }
+  },binding);
+ }
+}

package/tools/modules/minifish/harness/loading-observation.mjs

@@ -0,0 +1,25 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+// Optional read-only observation. No API override, DOM mutation or synthetic input.
+export async function installLoadingObservation(page){
+ const out=process.env.MINIFISH_LOADING_DIAGNOSTICS_DIR;
+ if(!out)return null;
+ const events=[],context=page.context();
+ const watch=p=>p.on('console',message=>{const text=message.text();if(text.startsWith('LOADING-OBS ')){try{events.push(JSON.parse(text.slice(12)));}catch{events.push({invalid:text});}}});
+ context.on('page',watch);watch(page);
+ await context.addInitScript(()=>{
+  const emit=value=>console.log('LOADING-OBS '+JSON.stringify({at:Date.now(),frame:location.href,dpr:devicePixelRatio,...value}));
+  for(const type of ['pointerdown','mousedown','click'])addEventListener(type,event=>{
+   const n=event.target;emit({kind:'input',type,x:event.clientX,y:event.clientY,target:n?.outerHTML?.slice(0,800)});
+  },true);
+  let previous='';
+  const observe=()=>{
+   const nodes=[...document.querySelectorAll('.adm-toast-loading')].map(n=>{const b=n.getBoundingClientRect();return {html:n.outerHTML.slice(0,600),width:b.width,height:b.height,left:b.left,top:b.top,visible:getComputedStyle(n).visibility,ancestor:n.closest('.adm-toast-wrap')?.outerHTML.slice(0,900)};});
+   const signature=JSON.stringify(nodes.map(({html,ancestor,...g})=>g));
+   if(signature!==previous){previous=signature;emit({kind:'loading-carriers',nodes});}
+  };
+  new MutationObserver(observe).observe(document,{childList:true,subtree:true});
+  addEventListener('DOMContentLoaded',observe,{once:true});
+ });
+ return {async save(){await fs.mkdir(out,{recursive:true});await fs.writeFile(path.join(out,'loading-input-observation.json'),JSON.stringify(events,null,2));context.off('page',watch);}};
+}

package/tools/modules/minifish/harness/local-navigation-evidence.mjs

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import {businessJsapiOption} from './jsapi.mjs';
+const registrations=new WeakMap(),contexts=new WeakMap();
+const copy=value=>JSON.parse(JSON.stringify(value));
+const pairs=params=>[...params].map(pair=>JSON.stringify(pair)).sort();
+function localUrl(raw,prefix){
+ assert.ok(typeof raw==='string'&&raw.startsWith(prefix)&&!raw.startsWith(prefix+'/'),'Exact local URL prefix required');
+ const rest=raw.slice(prefix.length);assert.ok(!rest.includes('#')&&!rest.includes('://'),'Local URL cannot contain host or fragment');
+ const path=rest.split('?')[0];assert.match(path,/^[\w/-]+$/);assert.ok(!path.startsWith('/'));
+ const parsed=new URL('/'+rest,'http://local.invalid');assert.equal(parsed.pathname.slice(1),path);
+ return {path,params:parsed.searchParams};
+}
+export function observeLocalNavigationCandidate(page,wire){
+ const target=wire.officialTarget;
+ if(target?.pageUrl&&target?.trAppId&&typeof target.trPageId==='string'&&target.contextType?.type==='app'&&target.contextType?.value==='mainApp')contexts.set(page,copy(target));
+}
+export function beginLocalNavigation(page,method,url){
+ if(method!=='navigateTo')return null;
+ const parsed=localUrl(url,'/');assert.equal(parsed.params.has('__appxPageId'),false,'Caller cannot supply reserved page ID');
+ const rows=registrations.get(page)??[];assert.equal(rows.some(row=>!row.closed),false,'Concurrent local registration rejected');
+ const source=contexts.get(page);assert.ok(source,'Previously observed official source context required');
+ assert.ok(page.frames().some(frame=>{try{const u=new URL(frame.url());return u.pathname+u.hash===source.pageUrl;}catch{return false;}}),'Source context must match a live public frame');
+ const record={method,url,path:parsed.path,query:pairs(parsed.params),source:copy(source),sourceFrames:page.frames().map(f=>f.url()),state:'registered',closed:false,consumed:false,candidates:[],officialCallback:null};
+ rows.push(record);registrations.set(page,rows);return record;
+}
+export function delegateLocalNavigation(page,wire){
+ if(wire.api!=='pushWindow')return false;
+ const option=businessJsapiOption(wire.option);
+ if(typeof option?.url!=='string'||!option.url.startsWith('#'))return false;
+ const record=(registrations.get(page)??[]).at(-1);
+ assert.ok(record&&!record.closed&&record.state==='registered','Local navigation needs one active unconsumed registration');
+ record.candidates.push(copy(wire));
+ assert.deepEqual(wire.officialTarget,record.source,'Official source context must exactly match registration');
+ assert.deepEqual(Object.keys(option).sort(),['launchParamsTag','url'],'Unexpected navigation option');
+ assert.equal(option.launchParamsTag,record.path);
+ const parsed=localUrl(option.url,'#');assert.equal(parsed.path,record.path);
+ const ids=parsed.params.getAll('__appxPageId');assert.equal(ids.length,1,'Exactly one runtime page ID required');
+ assert.match(ids[0],/^[1-9]\d*$/);assert.ok(Number.isSafeInteger(Number(ids[0])));
+ parsed.params.delete('__appxPageId');assert.deepEqual(pairs(parsed.params),record.query,'All business query entries must match');
+ record.runtimePageId=ids[0];record.runtimeIdentityQualification='official generated field, not independently preallocated';record.state='delegated';return true;
+}
+export async function finishLocalNavigation(page,record,outcome){
+ if(!record)return;
+ record.officialCallback=outcome;
+ try{
+  assert.equal(outcome.status,'success');assert.equal(record.state,'delegated','No matching official bridge delegation');
+  await expect.poll(async()=>{
+   for(const frame of page.frames()){
+    try{
+     const u=new URL(frame.url());if(!u.hash.startsWith('#'))continue;
+     const parsed=localUrl(u.hash,'#');if(parsed.path!==record.path)continue;
+     const ids=parsed.params.getAll('__appxPageId');if(ids.length>1)continue;
+     parsed.params.delete('__appxPageId');if(JSON.stringify(pairs(parsed.params))!==JSON.stringify(record.query))continue;
+     if(ids.length)assert.equal(ids[0],record.runtimePageId,'Public destination runtime ID');
+     if(!await frame.evaluate(()=>document.readyState==='complete'))continue;
+     const element=await frame.frameElement();const visible=await element.isVisible();await element.dispose();if(!visible)continue;
+     record.destination={url:frame.url(),publicPageId:ids[0]??null,ready:true};return true;
+    }catch(error){if(error.name==='AssertionError')throw error;}
+   }return false;
+  },{timeout:10000,intervals:[16,32,64,100],message:'Real official destination frame must be ready'}).toBe(true);
+  record.destinationFrames=page.frames().map(f=>f.url());record.state='target-ready';
+ }finally{record.closed=true;}
+}
+export function failLocalNavigation(record,error){if(record){record.closed=true;record.failure=error.message;}}
+export function assertLocalNavigationComplete(page,evidence,queryExpectations){
+ for(const row of registrations.get(page)??[]){
+  assert.equal(row.closed,true,'Registration must close');assert.equal(row.state,'target-ready');
+  const queryRows=queryExpectations(row,evidence);
+  row.preparatoryQueryIds=queryRows.map(x=>x.id);row.consumed=true;
+ }
+}
+export function localNavigationEvidence(page){return registrations.get(page)??[];}
+
+export async function observeLocalNavigationReturn(page){
+ const record=(registrations.get(page)??[]).at(-1);if(!record)return;
+ assert.equal(record.state,'target-ready');
+ const active='.simulator > .tr-page:not(:has(iframe.tr-page-iframe-animation-out)):not(:has(~ .tr-page:not(:has(iframe.tr-page-iframe-animation-out))))';
+ const root=page.frameLocator('iframe[name="lyra-integration-web-sdk"]').locator(active+' iframe[name="/'+record.path+'"]:not(.tr-page-iframe-animation-out):visible').contentFrame().locator('html');
+ await expect.poll(async()=>root.evaluate(()=>({url:location.pathname+location.hash,ready:document.readyState})),{timeout:10000,intervals:[16,32,64,100]}).toEqual({url:record.source.pageUrl,ready:'complete'});
+ record.returnLifecycle={activeUrl:record.source.pageUrl,ready:true,frames:page.frames().map(frame=>frame.url())};
+}

package/tools/modules/minifish/harness/miniapp-screenshot.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs/promises';
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import {activeShellSelector}from './browser.mjs';
+export function validateCaptureClip(box,viewport){
+ for(const key of ['x','y','width','height'])assert(Number.isFinite(box?.[key]),'Finite host screenshot bounds required');
+ assert(box.width>0&&box.height>0,'Positive host screenshot area');
+ const clip={x:Math.floor(box.x),y:Math.floor(box.y),width:Math.ceil(box.x+box.width)-Math.floor(box.x),height:Math.ceil(box.y+box.height)-Math.floor(box.y)};
+ assert(clip.x>=0&&clip.y>=0&&clip.x+clip.width<=viewport.width&&clip.y+clip.height<=viewport.height,'Entire host device must be inside screenshot viewport; capture never scrolls');return clip;
+}
+export async function observeMiniappGeometry(page){
+ const host=page.frameLocator('iframe[name="lyra-integration-web-sdk"]'),simulator=host.locator('.simulator');
+ await expect(simulator).toHaveCount(1);await expect(simulator).toBeVisible();
+ const geometry=await simulator.evaluate(node=>{const box=node.getBoundingClientRect();return {width:box.width,height:box.height,logicalWidth:node.offsetWidth,logicalHeight:node.offsetHeight,displayScaleX:box.width/node.offsetWidth,displayScaleY:box.height/node.offsetHeight,dpr:devicePixelRatio};});
+ expect(geometry.logicalWidth).toBe(402);expect(geometry.logicalHeight).toBe(874);
+ expect(geometry.width).toBeGreaterThan(0);expect(geometry.height).toBeGreaterThan(0);
+ const navigation=host.locator(activeShellSelector+' .lyra-page-title .titlebar');await expect(navigation).toHaveCount(1);await expect(navigation).toBeVisible();
+ return {...geometry,navigation:await navigation.boundingBox()};
+}
+export async function prepareMiniappCapture(page){
+ const geometry=await observeMiniappGeometry(page),simulator=page.frameLocator('iframe[name="lyra-integration-web-sdk"]').locator('.simulator');
+ const box=await simulator.boundingBox(),clip=validateCaptureClip(box,page.viewportSize()),nav=geometry.navigation;
+ assert(nav&&nav.x>=clip.x&&nav.y>=clip.y&&nav.x+nav.width<=clip.x+clip.width&&nav.y+nav.height<=clip.y+clip.height,'Actual SDK navigation must be inside captured device');
+ const dpr=await page.evaluate(()=>devicePixelRatio);
+ return {geometry,clip,dpr,preparedAt:new Date().toISOString()};
+}
+export async function captureMiniappScreenshot(page,info,phase,prepared){
+ const own=!prepared;prepared??=await prepareMiniappCapture(page);
+ const {geometry,clip,dpr,preparedAt}=prepared;
+ const evidence={phase,capturedAt:new Date().toISOString(),method:'read-only-page-clip-preflight-v3',preparedAt,preflightBeforeHeld:!own,logicalDevice:{width:402,height:874},geometry,clip,dpr,file:`miniapp-${phase}.png`};
+ // Public page capture never scrolls to an element or releases input.
+ // An artifact remains held until bytes are captured; formal behavior never waits.
+  const started=Date.now(),bytes=await page.screenshot({type:'png',clip,scale:'device',caret:'initial',animations:'allow'});
+  evidence.captureDurationMs=Date.now()-started;evidence.captureFinishedAt=new Date().toISOString();
+  assert.equal(bytes.readUInt32BE(16),Math.round(clip.width*dpr),'Screenshot device pixel width');assert.equal(bytes.readUInt32BE(20),Math.round(clip.height*dpr),'Screenshot device pixel height');
+  await fs.writeFile(info.outputPath(evidence.file),bytes);await fs.writeFile(info.outputPath(`miniapp-${phase}.json`),JSON.stringify(evidence,null,2));return evidence;
+
+}

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

@@ -0,0 +1,40 @@
+// 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 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);
+  const clipping=[];for(let n=el.parentElement;n;n=n.parentElement){const cs=getComputedStyle(n);if(['hidden','clip','auto','scroll'].some(v=>cs.overflowX===v||cs.overflowY===v)){const b=n.getBoundingClientRect();clipping.push({x:b.x,y:b.y,width:b.width,height:b.height});}}
+  const elements=[el,...el.querySelectorAll('*')];
+  const paintFor=n=>{
+   const ps=getComputedStyle(n),pr=n.getBoundingClientRect();let visible=true,opacity=1,owned=true;const clips=[];
+   for(let at=n;at;at=at.parentElement){const st=getComputedStyle(at);visible&&=st.display!=='none'&&st.visibility==='visible';opacity*=Number(st.opacity);if(at!==n){const b=at.getBoundingClientRect(),fractionX=['hidden','clip'].includes(st.overflowX),fractionY=['hidden','clip'].includes(st.overflowY),left=parseFloat(st.borderLeftWidth)||0,right=parseFloat(st.borderRightWidth)||0,top=parseFloat(st.borderTopWidth)||0,bottom=parseFloat(st.borderBottomWidth)||0;clips.push({x:b.x+(fractionX?left:at.clientLeft),y:b.y+(fractionY?top:at.clientTop),width:fractionX?b.width-left-right:at.clientWidth,height:fractionY?b.height-top-bottom:at.clientHeight,clipX:/hidden|clip|scroll|auto/.test(st.overflowX),clipY:/hidden|clip|scroll|auto/.test(st.overflowY)});}}
+   for(let at=n;at&&at!==el;at=at.parentElement)if(at.getAttribute('data-anchor-id'))owned=false;
+   return {paintIndex:elements.indexOf(n),owned,visible:visible&&opacity>0,frame:location.href,viewport:{width:innerWidth,height:innerHeight},box:{x:pr.x,y:pr.y,width:pr.width,height:pr.height},clipping:clips,styles:{objectFit:ps.objectFit,backgroundImage:ps.backgroundImage,backgroundSize:ps.backgroundSize,backgroundRepeat:ps.backgroundRepeat,backgroundPosition:ps.backgroundPosition},images:[{src:n.currentSrc||n.src||n.getAttribute('src')}]};
+  };
+  const imagePaints=elements.filter(n=>n.tagName==='IMG'||(n.getAttribute('role')==='img'&&getComputedStyle(n).backgroundImage!=='none')).map(paintFor);
+  const imagePaintInventory=elements.filter(n=>n.tagName==='IMG'||getComputedStyle(n).backgroundImage!=='none').map(paintFor);
+  return {imagePaints,imagePaintInventory,scrollWidth:el.scrollWidth,clientWidth:el.clientWidth,textStyles,clipping,viewport:{width:innerWidth,height:innerHeight},box:{x:r.x,y:r.y,width:r.width,height:r.height},styles,texts,frame:location.href,images:[el,...el.querySelectorAll('img')].map(n=>({src:n.currentSrc||n.src||n.getAttribute('src')}))};
+}
+
+export function sampleNativeTextVisibility(el){
+  const box=n=>{const r=n.getBoundingClientRect();return {x:r.x,y:r.y,width:r.width,height:r.height};};
+  const entries=[];const walk=n=>{if(n.nodeType===3&&n.textContent.trim()){
+   const range=document.createRange();range.selectNodeContents(n);let opacity=1,visible=true;const clips=[];
+   for(let p=n.parentElement;p;p=p.parentElement){const s=getComputedStyle(p);opacity*=Number(s.opacity);visible&&=s.visibility==='visible'&&s.display!=='none';const x=['hidden','clip','auto','scroll'].includes(s.overflowX),y=['hidden','clip','auto','scroll'].includes(s.overflowY);if(x||y){const b=box(p);clips.push({x:b.x+p.clientLeft,y:b.y+p.clientTop,width:p.clientWidth,height:p.clientHeight,clipX:x,clipY:y,self:p===el,ancestor:p!==el&&!el.contains(p),overflowX:s.overflowX,overflowY:s.overflowY,textOverflow:s.textOverflow,whiteSpace:s.whiteSpace,textAlign:s.textAlign,direction:s.direction,maxWidth:s.maxWidth,lineHeight:s.lineHeight});}}
+   const leaf=getComputedStyle(n.parentElement),styles=Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color'].map(k=>[k,leaf[k]]));let owned=true;for(let p=n.parentElement;p&&p!==el;p=p.parentElement)if(p.hasAttribute('data-anchor-id'))owned=false;
+   for(const r of range.getClientRects())if(r.width&&r.height)entries.push({styles,owned,range:{x:r.x,y:r.y,width:r.width,height:r.height},opacity,visible,clips});
+  }else for(const child of n.childNodes)walk(child);};walk(el);
+  const s=getComputedStyle(el);return {rawText:el.textContent,anchorId:el.getAttribute('data-anchor-id'),whiteSpace:s.whiteSpace,textAlign:s.textAlign,direction:s.direction,maxWidth:s.maxWidth,lineHeight:s.lineHeight,box:box(el),overflowX:s.overflowX,overflowY:s.overflowY,textOverflow:s.textOverflow,viewport:{x:0,y:0,width:innerWidth,height:innerHeight},entries};
+}
+
+export function sampleNativeStyle(el,{keys,pseudo}){return Object.fromEntries(keys.map(k=>[k,getComputedStyle(el,pseudo||null)[k]]));}
+export function sampleNativePressed(el){for(let n=el;n;n=n.parentElement)if(n.matches(':active'))return true;return false;}
+// Finite native DIV/SPAN/A carriers used by the held source contract. Other
+// renderer topologies must declare their state contract before native pressing.
+export function sampleHeldNativeState(el){
+ const s=getComputedStyle(el),b=el.getBoundingClientRect();
+ if(!['DIV','SPAN','A'].includes(el.tagName)||s.display==='contents')throw Error('Unsupported held native carrier topology');
+ return {visible:el.checkVisibility()&&s.visibility==='visible'&&b.width>0&&b.height>0,enabled:!el.closest('.a-button-disabled,[aria-disabled="true"],[disabled]:not([disabled="false"])')};
+}

package/tools/modules/minifish/harness/native-enabled.mjs

@@ -0,0 +1,11 @@
+import {expect} from '@playwright/test';
+// Observed official Minifish 2.40.1 button projection is a[role=button].
+// disabled=true projects a-button-disabled, without native disabled/aria-disabled.
+// Read only public carrier semantics; never assume an HTML button tag or mutate it.
+export async function isNativeEnabled(locator){
+ const disabled=await locator.evaluate(node=>Boolean(node.closest('.a-button-disabled,[aria-disabled="true"],[disabled]:not([disabled="false"])')));
+ return !disabled && await locator.isEnabled();
+}
+export async function waitNativeEnabled(locator,enabled,{timeout=10000}={}){
+ await expect.poll(()=>isNativeEnabled(locator),{timeout,message:'Public native carrier enabled state'}).toBe(enabled);
+}

package/tools/modules/minifish/harness/native-rpc-failure.mjs

@@ -0,0 +1,11 @@
+// Explicit native RPC failure callback; unlike success:false business data,
+// this travels through the official RPC transport envelope.
+export function rpcTransportFailure(error = 10001, errorMessage = 'mock network unavailable') {
+  return { $testTransportFailure: { error, errorMessage } };
+}
+export function rpcTransportEnvelope(result, encodeSuccess) {
+  if (!Object.hasOwn(result ?? {}, '$testTransportFailure')) return encodeSuccess(result);
+  const {error,errorMessage}=result.$testTransportFailure;
+  // Official SDK maps unsuccessful proxy code/message to native error -1.
+  return { success: false, code: error, message: errorMessage };
+}

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

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import {semanticLocator} from './semantic-anchor.mjs';
+import {expect} from '@playwright/test';
+
+export async function assertNativeState(locator, assertion) {
+  if (assertion.kind === 'hidden') {
+    assert((await locator.count()) <= 1, 'Duplicate hidden semantic target');
+    // Enumerate all carriers: absence is allowed, any visible duplicate fails.
+    for (let i=0; i<await locator.count(); i++) await expect(locator.nth(i)).toBeHidden();
+  } else if (assertion.kind === 'visible') {
+    await expect(locator).toHaveCount(assertion.count);
+    await expect(locator).toBeVisible();
+  } else throw Error(`Unsupported state assertion: ${assertion.kind}`);
+}

package/tools/modules/minifish/harness/native-ui-contract.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+export const nativeUiApis=['alert','showLoading','hideLoading','showToast','addToHomeWithGuideDialog'];
+export const nativeUiResultPath='/__bill_tests__/native-ui-result';
+export function validateNativeUiBoundary(row){
+ if(row.execution!=='official-ui')return false;
+ const api=row.request.operation.slice(6),p=row.request.params;
+ assert.equal(row.request.operation,'jsapi:'+api);assert(nativeUiApis.includes(api),'Finite official UI API list');
+ assert(p&&typeof p==='object'&&!Array.isArray(p),'UI object parameters');
+ const keys={alert:['title','content','buttonText'],showLoading:['content'],hideLoading:[],showToast:['content','type','delay','duration'],addToHomeWithGuideDialog:['appId','eventId']}[api];
+ assert(Object.keys(p).every(k=>keys.includes(k)),'Unexpected native UI parameter');
+ if(api==='alert'){assert.deepEqual(Object.keys(p).sort(),keys.slice().sort());for(const k of keys)assert(typeof p[k]==='string'&&p[k].length,'Nonempty alert field');}
+ if(api==='showLoading'&&p.content!==undefined)assert.equal(typeof p.content,'string');
+ if(api==='showToast'){assert(typeof p.content==='string'&&p.content.length);if(p.type!==undefined)assert(['success','fail','exception','none'].includes(p.type));for(const k of ['delay','duration'])if(p[k]!==undefined)assert(Number.isInteger(p[k])&&p[k]>=0);}
+ if(api==='addToHomeWithGuideDialog')assert.deepEqual(p,{appId:'20000193',eventId:'SHJF-HHBD'});
+ assert.deepEqual(row.outcome,{kind:'response',value:{}},'Official UI has no synthetic response');
+ assert.equal(row.times,1,'One exact official invocation per row');assert.equal(row.fixtureType,undefined,'Official UI cannot carry a Mock fixture type');
+ assert.equal(typeof row.requireConsumption,'boolean','Declare actual callback obligation');
+ return true;
+}
+export function validateNativeUiResult(receipt){
+ assert(receipt&&typeof receipt.api==='string'&&nativeUiApis.includes(receipt.api),'Actual official UI result required');
+ assert.equal(typeof receipt.resultPresent,'boolean');
+ if(receipt.resultPresent){
+  const v=receipt.result;assert(v===null||typeof v==='object','Native UI result must be a public object or null');
+  if(v?.error!==undefined)assert.equal(v.error,0,'Official UI failure cannot count as successful delegation');
+  if(v?.success!==undefined)assert.equal(v.success,true,'Official UI unsuccessful result');
+ }
+ return receipt;
+}

package/tools/modules/minifish/harness/navigation.mjs

@@ -0,0 +1,19 @@
+import {beginLocalNavigation,finishLocalNavigation,failLocalNavigation,observeLocalNavigationReturn} from './local-navigation-evidence.mjs';
+// Official public navigation; never calls product modules or page methods.
+export async function platformNavigate(page, method, url) {
+  if (!['navigateTo','redirectTo','navigateBack','startPullDownRefresh'].includes(method)) throw Error('Unsupported public navigation');
+  const registration=beginLocalNavigation(page,method,url);
+  try {await page.evaluate(async ({method,url}) => {
+    function find(window) {
+      try {
+        if (typeof window.my?.[method] === 'function') return window.my;
+        for (let i=0;i<window.frames.length;i++) { const api=find(window.frames[i]); if(api)return api; }
+      } catch {}
+      return null;
+    }
+    const api=find(window);
+    if(!api)throw Error(`Official public my.${method} unavailable`);
+    await new Promise((resolve,reject)=>api[method]({...(['navigateTo','redirectTo'].includes(method)?{url}:method==='navigateBack'?{delta:1}:{}),success:resolve,fail:reject}));
+  }, {method,url});await finishLocalNavigation(page,registration,{status:'success'});if(method==='navigateBack')await observeLocalNavigationReturn(page);
+  }catch(error){failLocalNavigation(registration,error);throw error;}
+}

package/tools/modules/minifish/harness/network_isolation.py

@@ -0,0 +1,134 @@
+"""One user/net namespace and userspace uplink per runner, never a shared lock."""
+import json
+import os
+from pathlib import Path
+import select
+import signal
+import subprocess
+import sys
+import time
+
+
+def add_network_arguments(parser):
+    parser.add_argument('--slirp4netns', type=Path, default=os.environ.get('MINIFISH_SLIRP4NETNS'), help='Explicit userspace network binary (required)')
+    parser.add_argument('--slirp-library-path', type=Path, default=os.environ.get('MINIFISH_SLIRP_LIBRARY_PATH'), help='Optional private dynamic library directory')
+
+
+def active_namespace(work):
+    metadata = os.environ.get('MINIFISH_RUN_NETWORK')
+    if not metadata:
+        return False
+    data = json.loads(metadata)
+    if data['reportDir'] != str(work) or data['netns'] != os.readlink('/proc/self/ns/net'):
+        raise RuntimeError('Run namespace metadata does not match current process')
+    return True
+
+
+def namespace_members(inode, exclude=()):
+    members = []
+    for proc in Path('/proc').glob('[0-9]*'):
+        try:
+            if int(proc.name) in exclude:
+                continue
+            fields = (proc / 'stat').read_text().rsplit(')', 1)[1].split()
+            if fields[0] != 'Z' and os.readlink(proc / 'ns/net') == inode:
+                members.append(int(proc.name))
+        except (FileNotFoundError, ProcessLookupError):
+            pass
+    return members
+
+
+def reap_namespace_members(inode, keeper_pid):
+    # SDK services may detach into new groups (e.g. NeoDebug Agent Hub).
+    # Namespace identity, not command-name matching, bounds cleanup to this run.
+    found = set(namespace_members(inode, (keeper_pid,)))
+    for sig, budget in ((signal.SIGTERM, 1), (signal.SIGKILL, 1)):
+        for pid in namespace_members(inode, (keeper_pid,)):
+            found.add(pid)
+            try: os.kill(pid, sig)
+            except ProcessLookupError: pass
+        deadline = time.monotonic() + budget
+        while namespace_members(inode, (keeper_pid,)) and time.monotonic() < deadline:
+            time.sleep(0.05)
+    remaining = namespace_members(inode, (keeper_pid,))
+    return {'detachedPids': sorted(found), 'remaining': remaining}
+
+
+def entry(work, args):
+    """Re-exec the whole runner inside its namespace, then reap all auxiliaries."""
+    if active_namespace(work):
+        return
+    if not args.slirp4netns or not args.slirp4netns.is_file():
+        raise RuntimeError('Set --slirp4netns or MINIFISH_SLIRP4NETNS; host-network fallback is forbidden')
+    children = []
+    child = None
+    ready_read = ready_write = None
+    info = {'reportDir': str(work), 'startedAt': time.time()}
+    handlers = {}
+    def interrupted(signum, frame):
+        if child is not None and child.poll() is None:
+            os.killpg(child.pid, signum)
+            return  # Keep the keeper/uplink alive until the inner runner has reaped its groups.
+        raise InterruptedError(f'Network runner interrupted by {signum}')
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        handlers[sig] = signal.signal(sig, interrupted)
+    try:
+        with (work / 'network.log').open('wb') as log:
+            keeper = subprocess.Popen(['unshare', '--user', '--map-root-user', '--net', 'sh', '-ec',
+                'ip link set lo up; echo $$; exec sleep infinity'], stdout=subprocess.PIPE, stderr=log, start_new_session=True)
+            children.append(keeper)
+            if not select.select([keeper.stdout], [], [], 15)[0]:
+                raise TimeoutError('Namespace keeper did not become ready')
+            line = keeper.stdout.readline()
+            if not line:
+                raise RuntimeError('Namespace creation failed; see network.log')
+            pid = int(line)
+            info.update(keeperPid=pid, netns=os.readlink(f'/proc/{pid}/ns/net'), userns=os.readlink(f'/proc/{pid}/ns/user'))
+            ready_read, ready_write = os.pipe()
+            uplink_env = dict(os.environ)
+            if args.slirp_library_path:
+                uplink_env['LD_LIBRARY_PATH'] = str(args.slirp_library_path.resolve())
+            slirp_argv = [str(args.slirp4netns.resolve()), '-c', '--disable-host-loopback', '-r', str(ready_write), str(pid), 'tap0']
+            slirp = subprocess.Popen(slirp_argv, env=uplink_env, pass_fds=[ready_write], stdout=log, stderr=log, start_new_session=True)
+            children.append(slirp)
+            os.close(ready_write); ready_write = None
+            if not select.select([ready_read], [], [], 15)[0] or not os.read(ready_read, 1):
+                raise RuntimeError('slirp network readiness failed; see network.log')
+            os.close(ready_read); ready_read = None
+            info.update(slirpPid=slirp.pid, slirpArgv=slirp_argv, readyAt=time.time())
+            (work / 'network.json').write_text(json.dumps(info, indent=2))
+            env = dict(os.environ, MINIFISH_RUN_NETWORK=json.dumps(info))
+            argv = ['nsenter', '--target', str(pid), '--user', '--net', '--', sys.executable, str(Path(sys.argv[0]).resolve()), *sys.argv[1:]]
+            # Outer entry generated a report dir when no explicit one was supplied.
+            if not args.report_dir:
+                argv += ['--report-dir', str(work)]
+            child = subprocess.Popen(argv, env=env, start_new_session=True)
+            children.append(child)
+            code = child.wait()
+    finally:
+        for sig in handlers:
+            signal.signal(sig, signal.SIG_IGN)
+        detached = reap_namespace_members(info['netns'], info['keeperPid']) if 'netns' in info else {'detachedPids': [], 'remaining': []}
+        for proc in reversed(children):
+            try: os.killpg(proc.pid, signal.SIGTERM)
+            except ProcessLookupError: pass
+        for proc in reversed(children):
+            try: proc.wait(timeout=5)
+            except subprocess.TimeoutExpired: pass
+            try: os.killpg(proc.pid, signal.SIGKILL)
+            except ProcessLookupError: pass
+            proc.wait()
+        for fd in (ready_read, ready_write):
+            if fd is not None: os.close(fd)
+        if children and children[0].stdout: children[0].stdout.close()
+        (work / 'network-lifecycle.json').write_text(json.dumps({'finishedAt': time.time(), 'network': info,
+            'namespaceCleanup': detached, 'children': [{'pid': p.pid, 'returncode': p.returncode} for p in children], 'cleanup': 'only this run network/runner process groups terminated and reaped'}, indent=2))
+        for sig, handler in handlers.items(): signal.signal(sig, handler)
+    if detached['remaining']:
+        raise RuntimeError('Run namespace has live detached services after cleanup')
+    raise SystemExit(code)
+
+
+def namespace_command(runtime):
+    network = runtime['network']
+    return ['nsenter', '--target', str(network['keeperPid']), '--user', '--net', '--']

package/tools/modules/minifish/harness/painted-source-image.mjs

@@ -0,0 +1,54 @@
+import {expect} from '@playwright/test';
+import {rendererImageEvidence,captureRendererImageEvidence} from './renderer-image-evidence.mjs';
+export {registerRendererImageEvidence} from './renderer-image-evidence.mjs';
+// HTML and native backgrounds are platform adapters, not required product DOM shapes.
+async function decodedHTMLImage(image,url,timeout){
+ await expect(image).toHaveCount(1,{timeout});await expect(image).toBeVisible({timeout});
+ const absolute=await image.evaluate((node,value)=>new URL(value,node.ownerDocument.baseURI).href,url);
+ await expect.poll(()=>image.evaluate(async(node,expected)=>{
+  try{await node.decode();}catch{return false;}
+  return node.currentSrc===expected&&node.complete&&node.naturalWidth>0&&node.naturalHeight>0;
+ },absolute),{timeout}).toBe(true);
+ return image.evaluate(node=>({src:node.currentSrc,width:node.naturalWidth,height:node.naturalHeight}));
+}
+
+// Public rendered carrier only: no DOM mutation or out-of-carrier image probes.
+export async function paintedSourceImage(host,url,{timeout=5000}={}){
+ await expect(host).toHaveCount(1,{timeout});await expect(host).toBeVisible({timeout});
+ // Observe content through the scroll container before testing viewport clipping.
+ await host.scrollIntoViewIfNeeded({timeout});
+ const state=await host.evaluate(node=>{
+  const style=getComputedStyle(node),box=node.getBoundingClientRect();
+  let opacity=1,left=Math.max(0,box.left),top=Math.max(0,box.top),right=Math.min(innerWidth,box.right),bottom=Math.min(innerHeight,box.bottom);
+  for(let p=node;p;p=p.parentElement){
+   const css=getComputedStyle(p);opacity*=Number(css.opacity);
+   if(p!==node){const clip=p.getBoundingClientRect();
+    if(/hidden|clip|scroll|auto/.test(css.overflowX)){left=Math.max(left,clip.left);right=Math.min(right,clip.right);}
+    if(/hidden|clip|scroll|auto/.test(css.overflowY)){top=Math.max(top,clip.top);bottom=Math.min(bottom,clip.bottom);}
+   }
+  }
+  return {tag:node.tagName,opacity,width:box.width,height:box.height,paintWidth:right-left,paintHeight:bottom-top,background:style.backgroundImage,size:style.backgroundSize};
+ });
+ expect(state.opacity).toBeGreaterThan(0);expect(state.width).toBeGreaterThan(0);expect(state.height).toBeGreaterThan(0);
+ expect(state.paintWidth).toBeGreaterThan(0);expect(state.paintHeight).toBeGreaterThan(0);
+ if(state.tag==='IMG'){const resource=await decodedHTMLImage(host,url,timeout);return {...state,mode:'html',resource};}
+ await expect(host).toHaveAttribute('role','img',{timeout});
+ if(state.background==='none'){
+  const resource=await decodedHTMLImage(host.locator('img'),url,timeout);
+  return {...state,mode:'html-in-semantic-carrier',resource};
+ }
+ // Compare the complete computed value, rejecting multiple layers and gradients.
+ const absolute=await host.evaluate((node,url)=>new URL(url,node.ownerDocument.baseURI).href,url);
+ expect(state.background).toBe(`url(${JSON.stringify(absolute)})`);
+ expect(state.size.split(/\s+/).some(value=>/^0(?:px|%)?$/.test(value))).toBe(false);
+ // Wait for actual response-byte decoding before observing the carrier resource.
+ const frame=await host.evaluate(node=>node.ownerDocument.location.href);
+ let record;
+ await expect.poll(async()=>{
+  await captureRendererImageEvidence(host.page());
+  record=rendererImageEvidence(host.page())?.find(r=>r.url===absolute&&r.frame===frame&&r.status>=200&&r.status<300&&r.decoded?.width>0&&r.decoded?.height>0);
+  return Boolean(record);
+ },{timeout,message:'Actual renderer response with decodable bytes before assertion probes: '+absolute}).toBe(true);
+ const resource={src:absolute,width:record.decoded.width,height:record.decoded.height,evidence:'same-frame-renderer-response-bytes',sha256:record.sha256};
+ return {...state,mode:'native-background',resource};
+}

package/tools/modules/minifish/harness/playwright.mjs

@@ -0,0 +1 @@
+export * from '@playwright/test';

package/tools/modules/minifish/harness/plugin-events.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+export function pluginEventLedger(plan,validatePluginEvents){
+ assert.equal(typeof validatePluginEvents,'function','Explicit plugin schema policy required');
+ validatePluginEvents(plan);const rows=[],violations=[];
+ return {receive(receipt){
+  try{const i=plan.instances.find(i=>i.id===receipt.instanceId);assert(i,'Wrong plugin instance');
+   assert.deepEqual(receipt.props,i.props,'Plugin actual props mismatch');
+   assert(['mounted','unmounted','event','callback'].includes(receipt.kind),'Unexpected plugin callback failure');
+   if(receipt.kind==='mounted'){assert(!rows.some(r=>r.instanceId===i.id&&r.kind==='mounted'),'Duplicate plugin mount');}
+   else if(receipt.kind!=='unmounted'){const e=i.events.find(e=>e.id===receipt.eventId);assert(e,'Unknown plugin event id');assert.equal(receipt.name,e.name);if(receipt.kind==='event'){assert(Number.isFinite(receipt.startedAt)&&receipt.at>=receipt.startedAt+e.delayMs,'Event before declared mount delay');if(rows.some(r=>r.instanceId===i.id&&r.kind==='unmounted'))assert(e.afterUnmount===true,'Unplanned event after unmount');}assert.deepEqual(receipt.payload,e.payload);assert(rows.some(r=>r.instanceId===i.id&&r.kind==='mounted'),'Event before real mount');
+    assert(!rows.some(r=>r.instanceId===i.id&&r.eventId===e.id&&r.kind===receipt.kind),'Duplicate plugin event receipt');
+    if(receipt.kind==='callback'&&Object.hasOwn(e,'callbackResponse'))assert.deepEqual(receipt.value,e.callbackResponse,'Public callback response mismatch');}
+   rows.push(structuredClone(receipt));
+  }catch(e){violations.push(e.message);throw e;}
+ },assertComplete(){assert.deepEqual(violations,[]);for(const i of plan.instances){assert(rows.some(r=>r.kind==='mounted'&&r.instanceId===i.id),'Missing real plugin mount');for(const e of i.events){for(const kind of ['event','callback'])assert(rows.some(r=>r.kind===kind&&r.instanceId===i.id&&r.eventId===e.id),'Missing plugin '+kind);}}},evidence(){return structuredClone({plan,rows,violations});}};
+}

package/tools/modules/minifish/harness/plugin-package.mjs

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+export function pluginPackagePlan({appAddress,appId,provider,version='*',packageBaseUrl,unavailable=false}) {
+ const base=new URL(packageBaseUrl);
+ assert.ok(['http:','https:'].includes(base.protocol));
+ assert.ok(['127.0.0.1','localhost','[::1]'].includes(base.hostname),'Plugin must be local compiled test resource');
+ assert.ok(base.pathname.endsWith('/'));
+ const expected={method:'getPkgInfo',params:[{address:appAddress.replace(/\/$/,'')+'/',appId},{provider,version}]};
+ const calls=[],violations=[],resources=[];
+ return {
+  calls,violations,resources,base:base.href,
+  handle(request){calls.push(structuredClone(request));try{
+   assert.deepEqual(request,expected,'Unexpected plugin discovery fields or values');
+   assert.equal(calls.length,1,'Duplicate plugin discovery');
+   return unavailable?{error:1,message:'controlled package unavailable'}:{error:0,data:{version:'dev',cdnBaseUrl:base.href}};
+  }catch(error){violations.push(error.message);throw error;}},
+  observe(response){if(response.ok()&&response.url().startsWith(base.href))resources.push(new URL(response.url()).pathname.split('/').at(-1));},
+  assertComplete({requireResources=!unavailable}={}){
+   assert.deepEqual(violations,[],'Plugin discovery violations');assert.equal(calls.length,1,'Missing plugin discovery');
+   if(requireResources)for(const name of ['appConfig.json','index.worker.js','index.js'])assert.ok(resources.includes(name),`Real plugin asset not loaded: ${name}`);
+  },
+  evidence(){return {calls,violations,resources,packageBaseUrl:base.href,unavailable};},
+ };
+}

package/tools/modules/minifish/harness/plugin_artifact.py

@@ -0,0 +1,23 @@
+"""Preflight compiled test plugin identity; no automatic compilation or fallback."""
+import hashlib
+import json
+from pathlib import Path
+
+
+def validate_plugin_artifact(artifact, source):
+    artifact, source = Path(artifact).resolve(), Path(source).resolve()
+    manifest = json.loads((artifact / 'plugin-artifact.json').read_text())
+    if manifest.get('schemaVersion') != 1 or not manifest.get('plan', {}).get('instances'):
+        raise ValueError('Explicit compiled plugin plan required')
+    expected = {str(p.relative_to(source)): hashlib.sha256(p.read_bytes()).hexdigest()
+                for p in sorted(source.rglob('*')) if p.is_file()}
+    if manifest.get('sourceHashes') != expected:
+        raise ValueError('Compiled plugin does not match frozen carrier source')
+    files = manifest.get('artifacts', {})
+    if not {'appConfig.json', 'index.js', 'index.worker.js'} <= files.keys():
+        raise ValueError('Incomplete official plugin artifacts')
+    for name, sha in files.items():
+        p = (artifact / name).resolve()
+        if artifact not in p.parents or not p.is_file() or hashlib.sha256(p.read_bytes()).hexdigest() != sha:
+            raise ValueError('Missing or changed compiled plugin artifact: ' + name)
+    return manifest

package/tools/modules/minifish/harness/product_identity.py

@@ -0,0 +1,8 @@
+"""Content identity of the actual copied product, independent of branch labels."""
+import hashlib
+import json
+
+
+def product_identity(files):
+    encoded = json.dumps(files, sort_keys=True, ensure_ascii=False, separators=(',', ':')).encode()
+    return {'sha256': hashlib.sha256(encoded).hexdigest(), 'kind': 'product-source-content'}