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

package/tools/modules/minifish/harness/semantic-anchor.mjs

@@ -0,0 +1,139 @@
+import {expect} from '@playwright/test';
+// Platform-only adapter. Case definitions use source paths, never this DOM API.
+export const anchorAdapterVersion = 'minifish-2.40.1-appxng-dataset-v2';
+
+export function anchorSelector(path) {
+  if (typeof path !== 'string' || !path.trim() || /\u0000|[\uD800-\uDFFF]/u.test(path)) {
+    throw new Error('Invalid semantic anchor path');
+  }
+  // Hex escapes work for quotes, slashes, newlines and non-ASCII characters alike.
+  const escaped = Array.from(path, c => `\\${c.codePointAt(0).toString(16)} `).join('');
+  return `[data-anchor-id="${escaped}"]`;
+}
+
+/** Serialized into the actual business frame; never the React simulator shell. */
+export function synchronizeNativeAnchors(root) {
+  const doc = root.ownerDocument;
+  const win = doc.defaultView;
+  const key = '__seeleSemanticAnchorsV2';
+  const state = win[key] ?? (win[key] = {owned: new Map(), instances: new Map()});
+  if (state.error) throw new Error(state.error);
+  state.instances ??= new Map();
+  const attr = 'data-anchor-id';
+  const instanceAttr = 'data-anchor-instance';
+  const releaseInstance = node => {
+    const previous = state.instances.get(node);
+    if (previous === undefined) return;
+    if (node.getAttribute(instanceAttr) !== previous) throw Error('Source instance modified outside adapter');
+    node.removeAttribute(instanceAttr);
+    state.instances.delete(node);
+  };
+  let synchronized = 0;
+  let recognized = false;
+  for (const node of doc.querySelectorAll('*')) {
+    if (Object.prototype.hasOwnProperty.call(node, '$$dataset')) recognized = true;
+    const data = node.$$dataset;
+    const marker = data && Object.prototype.hasOwnProperty.call(data, 'anchorId') ? data.anchorId : undefined;
+    const previous = state.owned.get(node);
+    if (typeof marker === 'string' && marker.length) {
+      const actual = node.getAttribute(attr);
+      if (actual !== null && actual !== marker && actual !== previous) {
+        throw new Error(`Conflicting semantic anchor: ${marker}`);
+      }
+      if (actual !== marker) {
+        node.setAttribute(attr, marker);
+        state.owned.set(node, marker);
+      } else if (previous !== undefined) state.owned.set(node, marker);
+      const instance=data?.anchorInstance;
+      if(instance!==undefined&&instance!==null&&instance!==''){
+        if(!/^(0|[1-9]\d*)$/.test(String(instance))||!Number.isSafeInteger(Number(instance)))throw Error('Invalid declared source instance');
+        const declared=String(instance), actualInstance=node.getAttribute(instanceAttr), previousInstance=state.instances.get(node);
+        if(actualInstance!==null&&actualInstance!==declared&&actualInstance!==previousInstance)throw Error('Conflicting source instance');
+        if(actualInstance!==declared){node.setAttribute(instanceAttr,declared);state.instances.set(node,declared);}
+        else if(previousInstance!==undefined)state.instances.set(node,declared);
+      }else releaseInstance(node);
+      synchronized++;
+    } else if (previous !== undefined) {
+      if (node.getAttribute(attr) !== previous) throw new Error('Semantic anchor modified outside adapter');
+      node.removeAttribute(attr);releaseInstance(node);
+      state.owned.delete(node);
+    }
+  }
+  for (const [node, marker] of state.owned) {
+    if (!node.isConnected) {
+      if (node.getAttribute(attr) !== marker)throw Error('Semantic anchor modified outside adapter');
+      node.removeAttribute(attr);
+      state.owned.delete(node);
+    }
+  }
+  for(const node of state.instances.keys())if(!node.isConnected || !node.$$dataset?.anchorId)releaseInstance(node);
+  if (recognized) state.capabilityConfirmed = true;
+  if (!state.capabilityConfirmed) throw new Error('Unsupported business renderer: AppX-NG dataset capability absent');
+  if (!state.timer && typeof win.setInterval === 'function') {
+    state.timer = win.setInterval(() => {
+      try { synchronizeNativeAnchors(root); }
+      catch (error) { state.error = error.message; win.clearInterval(state.timer); }
+    }, 50);
+  }
+  return {adapter: 'minifish-2.40.1-appxng-dataset-v2', synchronized};
+}
+
+export async function synchronizeAnchors(root) {
+  await expect.poll(() => root.locator(':root').evaluate(el => {
+    const doc=el.ownerDocument;
+    return !!doc.defaultView.__seeleSemanticAnchorsV2?.capabilityConfirmed || Array.from(doc.querySelectorAll('*')).some(n => Object.prototype.hasOwnProperty.call(n, '$$dataset'));
+  }), {timeout:10000,message:'Wait for actual AppX-NG business renderer capability; unsupported renderers fail'}).toBe(true);
+  return root.locator(':root').evaluate(synchronizeNativeAnchors);
+}
+
+// Call on every observation attempt, including polling, so a dataset-only update
+// cannot leave the previously synchronized identity in use.
+export async function resolveAnchor(root, path, {allowAbsent = false, instance} = {}) {
+  await synchronizeAnchors(root);
+  const locator = semanticLocator(root, path, {instance});
+  const count = await locator.count();
+  if (count > 1 || (!allowAbsent && count !== 1)) {
+    throw new Error(`Semantic anchor must be unique: ${path}; found ${count}`);
+  }
+  return locator;
+}
+
+export function semanticLocator(root, path, {instance} = {}) {
+ let selector=anchorSelector(path);
+ if(instance!==undefined){validateSemanticInstance(instance);selector+='[data-anchor-instance="'+instance+'"]';}
+ return root.locator(selector);
+}
+
+export async function closeAnchors(root) {
+  await root.locator(':root').evaluate(el => {
+    const win = el.ownerDocument.defaultView, state = win.__seeleSemanticAnchorsV2;
+    if (!state) return;
+    win.clearInterval(state.timer);
+    for (const [node, marker] of state.owned) if (node.getAttribute('data-anchor-id') === marker) {node.removeAttribute('data-anchor-id');}
+    for (const [node, instance] of state.instances ?? []) {
+      if(node.getAttribute('data-anchor-instance') !== instance)throw Error('Source instance modified outside adapter');
+      node.removeAttribute('data-anchor-instance');
+    }
+    delete win.__seeleSemanticAnchorsV2;
+    if (state.error) throw Error(state.error);
+  });
+}
+
+// Read the same public renderer dataset used by synchronizeNativeAnchors,
+// without changing attributes or waiting for its timer during held input.
+export function readNativeSemanticIdentity(node){
+ if(Object.prototype.hasOwnProperty.call(node,'$$dataset')){
+  const data=node.$$dataset;
+  return {path:typeof data?.anchorId==='string'&&data.anchorId?data.anchorId:null,instance:data?.anchorInstance===undefined||data?.anchorInstance===null||data?.anchorInstance===''?null:String(data.anchorInstance)};
+ }
+ return {path:node.getAttribute('data-anchor-id'),instance:node.getAttribute('data-anchor-instance')};
+}
+
+// Undefined is an omitted constraint, never a request for an uninstanced node.
+export function validateSemanticInstance(instance){
+ if(instance!==undefined&&(!Number.isSafeInteger(instance)||instance<0))throw Error('Invalid source instance');
+ return instance;
+}
+export function matchesNativeSemanticIdentity(identity,path,instance){
+ return identity.path===path&&(instance===undefined||identity.instance===String(instance));
+}

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

@@ -0,0 +1,197 @@
+import {sampleNativeTextVisibility,sampleNativeStyle,sampleNativePressed} from './native-dom-sampling.mjs';
+import {near,geometryNear} from './independent-visual.mjs';
+// Public platform-only read/expect surface. No business selectors or expectations.
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+export {expect};
+// Share the existing strict native editor resolver used by public input actions.
+import {editableCarrier} from './target-actions.mjs';
+export {editableCarrier};
+import {semanticLocator} from './semantic-anchor.mjs';
+export {semanticLocator};
+export function semanticCollection(root,paths){
+ if(!Array.isArray(paths)||!paths.length||new Set(paths).size!==paths.length)throw Error('Collection requires distinct declared source paths');
+ return paths.map(path=>semanticLocator(root,path)).reduce((collection,node)=>collection.or(node));
+}
+export function nativePart(node,{role,index}={}){
+ const roles={text:'.a-text',img:'[role="img"]',button:'[role="button"]',separator:'[role="separator"]',presentation:'[role="presentation"]'};
+ if(!roles[role])throw Error('Unknown native part role');
+ const part=node.locator(roles[role]);return index===undefined?part:part.nth(index);
+}
+export async function nativeAttribute(node,name){return node.getAttribute(name);}
+// Editor-only attribute observation; preserve the semantic wrapper for geometry.
+export async function nativeEditableAttribute(node,name,{timeout=10000}={}){
+ assert(['maxlength','placeholder'].includes(name),'Only declared editable maxlength/placeholder attributes');
+ const editor=await editableCarrier(node,timeout);
+ let value=await editor.getAttribute(name);
+ if(name==='placeholder'&&value===null){
+  // Public SDK input renders its placeholder as a sibling entity, not an HTML attribute.
+  value=await editor.evaluate(input=>{
+   const wrapper=input.closest('.a-input'),wrap=input.parentElement;
+   if(!wrapper||!wrap?.classList.contains('a-input-wrap')||input.value!=='')return null;
+   const nodes=[...wrap.children].filter(e=>e.classList.contains('a-input-placeholder'));
+   if(nodes.length!==1)return null;
+   const node=nodes[0],leaves=node.querySelectorAll('span');if(leaves.length!==1)return null;
+   for(let e=leaves[0];e;e=e.parentElement){const s=getComputedStyle(e);if(s.display==='none'||s.visibility!=='visible'||Number(s.opacity)===0)return null;if(e===wrapper)break;}
+   const box=leaves[0].getBoundingClientRect();if(box.width<=0||box.height<=0)return null;
+   return leaves[0].innerText||null;
+  });
+ }
+ assert(value!==null,'Native editable attribute is missing: '+name);
+ return value;
+}
+export async function nativeStyle(node,keys,pseudo){return node.evaluate(sampleNativeStyle,{keys,pseudo});}
+export async function nativePaint(node){return node.evaluate(e=>{let opacity=1;for(let n=e;n;n=n.parentElement)opacity*=Number(getComputedStyle(n).opacity);const r=e.getBoundingClientRect(),hit=document.elementFromPoint(r.x+r.width/2,r.y+r.height/2);return {opacity,hit:!!hit&&(hit===e||e.contains(hit))};});}
+export async function nativeBorder(node){return node.evaluate(e=>{const s=getComputedStyle(e);return {width:parseFloat(s.borderTopWidth),style:s.borderTopStyle,color:s.borderTopColor,dpr:devicePixelRatio};});}
+export async function nativeDivider(node){const s=await nativeStyle(node,['content','height','borderLeftWidth','borderLeftColor'],'::before');return {content:s.content,height:parseFloat(s.height),width:parseFloat(s.borderLeftWidth),color:s.borderLeftColor};}
+export async function nativeConnector(node){const part=nativePart(node,{role:'presentation'});if(await part.count()>1)throw Error('Duplicate native decoration');return nativeStyle(await part.count()?part:node,['content','left','top','width','height','backgroundColor'],await part.count()?undefined:'::after');}
+export function nativeParent(node){return node.locator('..');}
+
+export async function resolveSemanticCollection(root,paths){
+ for(const path of paths)assert((await semanticLocator(root,path).count())<=1,'Duplicate declared collection member');
+ return semanticCollection(root,paths);
+}
+export async function assertSourceInstances(node,indices){
+ await expect(node).toHaveCount(indices.length);
+ for(const [i,index]of indices.entries()){
+  assert(Number.isSafeInteger(index)&&index>=0,'Invalid declared source order');
+  assert.equal(await node.nth(i).getAttribute('data-anchor-instance'),String(index),'Rendered collection source order');
+ }
+}
+export async function nativePressed(node){return node.evaluate(sampleNativePressed);}
+
+export function nativeNext(node){return node.locator('xpath=following-sibling::*[1]');}
+
+export function validateNativeTextStyles(leaves,wanted,u=1){
+ assert(leaves.length,'Actual owned native text leaf required');
+ for(const leaf of leaves)for(const [key,value]of Object.entries(wanted??{})){
+  if(typeof value==='number'&&key!=='fontWeight')near(parseFloat(leaf[key]),value*u,'leaf '+key);
+  else assert.equal(key==='fontWeight'?Number(leaf[key]):leaf[key],value,'leaf '+key);
+ }
+}
+// Read actual text paint boundaries; a visible-overflow source box is not a clip.
+export async function observeNativeTextVisibility(node,{selfOverflow='contain',sourceTarget,expected}={}){
+ assert(['contain','visible'].includes(selfOverflow),'Unknown source text display policy');
+ const evidence=await node.evaluate(sampleNativeTextVisibility);
+ return validateNativeTextVisibility(evidence,{selfOverflow,sourceTarget,expected});
+}
+export function validateNativeTextVisibility(evidence,{selfOverflow='contain',sourceTarget,expected}={}){
+ assert(['contain','visible'].includes(selfOverflow),'Unknown source text display policy');
+ try {
+ if(selfOverflow==='visible'){assert.equal(evidence.overflowX,'visible','Source permits visible self overflow');assert.equal(evidence.overflowY,'visible','Source permits visible self overflow');assert.equal(evidence.textOverflow,'clip','Source text-overflow clip');}
+ for(const entry of evidence.entries){assert(entry.visible&&entry.opacity>0,'Text must actually paint');const bounds=[...entry.clips,{...evidence.viewport,clipX:true,clipY:true},...(selfOverflow==='contain'?[{...evidence.box,clipX:true,clipY:true}]:[])];
+  for(const b of bounds){const r=entry.range;if(b.clipX)assert(r.x>=b.x-.5&&r.x+r.width<=b.x+b.width+.5,'Actual text horizontal clipping');if(b.clipY)assert(r.y>=b.y-.5&&r.y+r.height<=b.y+b.height+.5,'Actual text vertical clipping');}
+ }
+ return evidence;
+ }catch(error){error.message+='\nNative text evidence: '+JSON.stringify(evidence);throw error;}
+}
+
+// Official SDK checkbox: role carrier owns one direct typed checkbox input.
+// Read state from the real native input and aria, never a business class/prop.
+export async function nativeCheckbox(node){
+ const carrier=node.locator('[role="checkbox"]');
+ const selfRole=await node.getAttribute('role');
+ const circle=selfRole==='checkbox'?node:carrier;
+ await expect(circle).toHaveCount(1);
+ const state=await circle.evaluate(el=>{
+  const inputs=[...el.children].filter(n=>n.tagName==='INPUT'&&n.type==='checkbox');
+  assertNative(inputs.length===1,'Checkbox must own one direct native input');
+  const input=inputs[0],aria=el.getAttribute('aria-checked');
+  assertNative(aria==='true'||aria==='false','Native checkbox aria state');
+  assertNative(input.checked===(aria==='true'),'Native input and aria must agree');
+  const paths=[...el.querySelectorAll('svg path')].map(p=>({fill:getComputedStyle(p).fill,stroke:getComputedStyle(p).stroke,d:p.getAttribute('d')}));
+  return {checked:input.checked,enabled:!input.disabled,aria,paths};
+  function assertNative(ok,message){if(!ok)throw Error(message);}
+ });
+ return {circle,state};
+}
+
+export async function assertNativeOwnership(parent,child,{instance}={}){
+ await expect(parent).toHaveCount(1);await expect(child).toHaveCount(1);
+ const parentHandle=await parent.elementHandle();
+ try{assert(await child.evaluate((el,p)=>p!==el&&p.contains(el),parentHandle),'Actual native child must belong to selected source parent');}
+ finally{await parentHandle.dispose();}
+ if(instance!==undefined){assert.equal(await parent.getAttribute('data-anchor-instance'),String(instance));assert.equal(await child.getAttribute('data-anchor-instance'),String(instance));}
+}
+
+// A same-document native renderer reference, not mathematical DPR flooring.
+// This observes CSS used border geometry; it does not certify raster screenshots.
+export async function nativeBorderReference(node,{width,designWidth=375,unit='scaled',side='top',style='solid',color}={}){
+ assert(Number.isFinite(width)&&width>0,'Positive declared source border');assert(['scaled','px'].includes(unit));assert(['top','right','bottom','left'].includes(side));assert(['solid','dashed'].includes(style));
+ return node.evaluate((el,spec)=>{
+  const cssWidth=spec.width*(spec.unit==='px'?1:innerWidth/spec.designWidth);
+  const reference=el.ownerDocument.createElement('div');
+  reference.setAttribute('aria-hidden','true');
+  reference.style.cssText='all:initial;position:fixed;left:0;top:0;display:block;width:10px;height:10px;box-sizing:content-box;pointer-events:none;z-index:2147483647;background:transparent;';
+  const cap=spec.side[0].toUpperCase()+spec.side.slice(1);
+  reference.style['border'+cap]=cssWidth+'px '+spec.style+' '+spec.color;
+  el.ownerDocument.body.append(reference);
+  try{const s=getComputedStyle(reference),b=reference.getBoundingClientRect(),used=parseFloat(s['border'+cap+'Width']);
+   if(!(used>0&&b.width>0&&b.height>0&&devicePixelRatio>0))throw Error('Native reference must have nonzero actual used border geometry');
+   return {width:used,style:s['border'+cap+'Style'],color:s['border'+cap+'Color'],dpr:devicePixelRatio,requestedCssWidth:cssWidth,side:spec.side,frame:location.href,referenceBox:{width:b.width,height:b.height},level:'same-frame-native-css-used-border'};
+  }finally{reference.remove();}
+ },{width,designWidth,unit,side,style,color});
+}
+
+// Finite native topology of a selected source card/header. No business classes,
+// visible-text filtering, props, or fabricated semantic anchors.
+export async function nativeVoucherParts(node,kind){
+ assert(['card','sheet'].includes(kind),'Finite native voucher part scope');
+ const views=node.locator(':scope > .a-view');await expect(views).toHaveCount(2);
+ if(kind==='sheet')return {header:views.nth(0),list:views.nth(1)};
+ const value=views.nth(0),copy=views.nth(1),currency=value.locator(':scope > .a-text').nth(1),watermark=node.locator(':scope > .a-text[aria-hidden="true"]');
+ const texts=value.locator(':scope > .a-text');const count=await texts.count();assert([2,3].includes(count),'Exact native value/currency/optional restriction topology');
+ assert((await watermark.count())<=1,'Duplicate native watermark');
+ return {value,copy,currency,watermark,valueTextCount:count};
+}
+
+// Resolve an inner content group by ownership and painted-child structure,
+// never by expected text, color, dimensions, class or prototype HTML tags.
+export async function nativeInnerBox(node){
+ const evidence=await node.evaluate(root=>{
+  const rect=e=>{const b=e.getBoundingClientRect();return {x:b.x,y:b.y,width:b.width,height:b.height};};
+  const visible=e=>{const b=rect(e);if(!b.width||!b.height)return false;for(let p=e;p;p=p.parentElement){const s=getComputedStyle(p);if(s.display==='none'||s.visibility!=='visible'||Number(s.opacity)===0)return false;if(p===root)break;}return true;};
+  const text=[];const walker=document.createTreeWalker(root,NodeFilter.SHOW_TEXT);
+  for(let n=walker.nextNode();n;n=walker.nextNode())if(n.textContent.trim()&&visible(n.parentElement))text.push(n);
+  if(!text.length)throw Error('Inner box requires painted text');
+  let box;
+  for(let p=text[0].parentElement;p&&p!==root;p=p.parentElement){
+   if(!text.every(n=>p.contains(n)))continue;
+   const children=[...p.children].filter(visible);
+   if(children.length===2&&children.filter(c=>text.some(n=>c.contains(n))).length===1){box=p;break;}
+  }
+  if(!box)throw Error('Source-owned inner content box missing; root cannot substitute');
+  // Painted rectangles remain evidence. Layout uses fractional used border sizes
+  // and removes each child's own transform in the inner box's logical frame.
+  const borderSize=e=>{
+   const s=getComputedStyle(e),n=k=>{const v=Number.parseFloat(s[k]);if(!Number.isFinite(v))throw Error('Unresolved public layout dimension: '+k);return v;};
+   return {width:n('width')+(s.boxSizing==='border-box'?0:n('paddingLeft')+n('paddingRight')+n('borderLeftWidth')+n('borderRightWidth')),height:n('height')+(s.boxSizing==='border-box'?0:n('paddingTop')+n('paddingBottom')+n('borderTopWidth')+n('borderBottomWidth'))};
+  };
+  const matrix=e=>{
+   const s=getComputedStyle(e);
+   if((s.rotate&&s.rotate!=='none')||(s.scale&&s.scale!=='none')||(s.translate&&s.translate!=='none')||(s.perspective&&s.perspective!=='none')||(s.zoom&&Number(s.zoom)!==1))throw Error('Unsupported independent public layout transform');
+   const m=new DOMMatrixReadOnly(s.transform==='none'?undefined:s.transform);
+   if(!m.is2D)throw Error('Unsupported 3D public layout transform');
+   return m;
+  };
+  let scaleX=1,scaleY=1;
+  for(let p=box;p;p=p.parentElement){const m=matrix(p);if(Math.abs(m.b)>1e-10||Math.abs(m.c)>1e-10||m.a<=0||m.d<=0)throw Error('Unsupported non-axis public layout ancestor transform');scaleX*=m.a;scaleY*=m.d;}
+  const paintedBox=rect(box),size=borderSize(box);
+  if(Math.abs(paintedBox.width/scaleX-size.width)>.25||Math.abs(paintedBox.height/scaleY-size.height)>.25)throw Error('Public layout frame dimension mismatch');
+  const childNodes=[...box.children].filter(visible),children=childNodes.map(rect);
+  const layoutChildren=childNodes.map(e=>{
+   const size=borderSize(e),m=matrix(e),origin=getComputedStyle(e).transformOrigin.split(' ').map(Number.parseFloat),painted=rect(e);
+   if(!origin.every(Number.isFinite))throw Error('Unresolved public transform origin');
+   const corners=[[0,0],[size.width,0],[0,size.height],[size.width,size.height]].map(([x,y])=>({x:m.a*(x-origin[0])+m.c*(y-origin[1])+m.e+origin[0],y:m.b*(x-origin[0])+m.d*(y-origin[1])+m.f+origin[1]}));
+   const xs=corners.map(p=>p.x),ys=corners.map(p=>p.y),minX=Math.min(...xs),minY=Math.min(...ys);
+   if(Math.abs(painted.width/scaleX-(Math.max(...xs)-minX))>.25||Math.abs(painted.height/scaleY-(Math.max(...ys)-minY))>.25)throw Error('Public transformed child dimension mismatch');
+   return {x:(painted.x-paintedBox.x)/scaleX-minX,y:(painted.y-paintedBox.y)/scaleY-minY,...size};
+  });
+  const layout={coordinateSpace:'inner-border-box-css-px',box:{x:0,y:0,...size},children:layoutChildren};
+  const s=getComputedStyle(box);
+  return {ownership:'descendant-of-semantic-carrier',box:paintedBox,children,layout,styles:Object.fromEntries(['backgroundColor','paddingTop','paddingRight','paddingBottom','paddingLeft','borderRadius','gap','display','flexDirection','alignItems'].map(k=>[k,s[k]]))};
+ });
+ assert.equal(evidence.ownership,'descendant-of-semantic-carrier');return evidence;
+}
+
+export async function sampleTextVisibility(node){return node.evaluate(sampleNativeTextVisibility);}

package/tools/modules/minifish/harness/skeleton-appearance.mjs

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import {nativeMetrics,near,geometryNear} from './independent-visual.mjs';
+
+export function assertSkeletonReceipt(records,m,a) {
+ const receipts=records.filter(r=>r.url===a.expected&&r.frame===m.frame&&r.frameId===m.frameId);
+ assert(receipts.some(r=>r.status===200&&r.bytes>0&&r.sha256&&r.decoded?.width===a.naturalWidth&&r.decoded?.height===a.naturalHeight&&!r.decodeError),'Same renderer/frame successful original bytes decode to source dimensions');
+}
+export function assertSkeletonSource(m,a) {
+ if(m.image.styles.backgroundImage!=='none')assert.equal(m.image.styles.backgroundImage,`url("${a.expected}")`,'Exact sole painted background source');
+ else assert.equal(m.painting.src,a.expected,'Actual image carrier source; hidden descendants cannot substitute');
+}
+export async function skeletonMetrics(locator,region) {
+ const image=await nativeMetrics(locator),container=await nativeMetrics(region);
+ const painting=await locator.evaluate(el=>{const s=getComputedStyle(el);return {backgroundSize:s.backgroundSize,backgroundPosition:s.backgroundPosition,backgroundRepeat:s.backgroundRepeat,objectFit:s.objectFit,objectPosition:s.objectPosition,tag:el.tagName,src:el.currentSrc||el.src||el.getAttribute('src')};});
+ const clipping=await region.evaluate(el=>{const s=getComputedStyle(el);return {overflowX:s.overflowX,overflowY:s.overflowY,scrollWidth:el.scrollWidth,clientWidth:el.clientWidth};});
+ return {image,container,painting,clipping};
+}
+export function assertSkeletonGeometry(m,a) {
+ const {image:i,container:c,painting:p,clipping:k}=m;
+ geometryNear(i.viewport.width,a.logicalWidth,'logical width');geometryNear(i.viewport.height,a.logicalHeight,'business viewport');
+ geometryNear(c.box.x,0,'region left');geometryNear(c.box.y,0,'region top');geometryNear(c.box.width,i.viewport.width,'region width');geometryNear(c.box.height,i.viewport.height,'region full business height');
+ geometryNear(i.box.x,c.box.x,'image left');geometryNear(i.box.y,c.box.y,'image top');geometryNear(i.box.width,c.box.width,'fill width');geometryNear(i.box.height,c.box.width*a.naturalHeight/a.naturalWidth,'source aspect ratio');
+ assert.equal(c.styles.backgroundColor,a.backgroundColor,'loading background');
+ assert(['hidden','clip'].includes(k.overflowX)&&['hidden','clip'].includes(k.overflowY),'Source overflow clips both axes');
+ assert(k.scrollWidth<=k.clientWidth,'No horizontal overflow');
+ if(i.styles.backgroundImage!=='none') {
+  assertSkeletonSource(m,a);
+  assert(['100% 100%','100% auto','contain','cover'].includes(p.backgroundSize),'Native background fit preserves source aspect ratio in equal-ratio carrier');
+  assert(['0% 0%','0px 0px','50% 50%'].includes(p.backgroundPosition),'Native background position matches full carrier');
+  assert.equal(p.backgroundRepeat,'no-repeat','No repeated image');
+ } else {
+  assert.equal(p.src,a.expected,'Actual native image source');
+  assert(['fill','contain','cover'].includes(p.objectFit),'Image painting fits equal-ratio carrier');
+  assert(['50% 50%','0% 0%','0px 0px'].includes(p.objectPosition),'Native image position');
+ }
+}
+export async function assertSkeletonAppearance(locator,region,a,images) {
+ await expect(locator).toHaveCount(1);await expect(region.getByRole('img')).toHaveCount(1);await expect(locator).toBeVisible();await expect(locator).toHaveRole('img');
+ if(a.kind==='skeleton-content')await expect(locator).toHaveAccessibleName(a.name,{exact:true});
+ const m=await skeletonMetrics(locator,region);
+ const handle=await locator.elementHandle();try{m.image.frameId=images.frameId(await handle.ownerFrame());}finally{await handle.dispose();}
+ if(a.kind==='skeleton-content') {
+  assertSkeletonSource(m,a);
+  await expect.poll(()=>{try{assertSkeletonReceipt(images.records,m.image,a);return true;}catch{return false;}},{message:'Actual renderer receipt and original response decode'}).toBe(true);
+  assertSkeletonReceipt(images.records,m.image,a);
+ }else assertSkeletonGeometry(m,a);
+ return m;
+}

package/tools/modules/minifish/harness/target-actions.mjs

@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict';
+import {validateLifecycleAction} from './retained-page-lifecycle.mjs';
+import {expect} from '@playwright/test';
+import {waitNativeEnabled} from './native-enabled.mjs';
+import {waitForNativeInput} from './loading-input.mjs';
+export function validateTargetActions(before=[],after=[],boundaries=[]) {
+ assert(Array.isArray(before)&&Array.isArray(after),'Target actions must be arrays');
+ const ids=new Set(),released=new Set();let pressed=null;
+ for(const [phase,items] of [['before',before],['after',after]])for(const a of items){
+  assert(a && typeof a.id==='string' && a.id.trim(),'Action id required');assert(!ids.has(a.id),'Duplicate target action id');ids.add(a.id);
+  assert(['click','press','release','wait-state','input','focus','blur','clear','release-boundary','leave-return'].includes(a.kind),'Unknown target action kind');
+  for(const key of ['selector','locator','evaluate','getByText','getByRole','xpath'])assert(!Object.hasOwn(a,key),'Forbidden DOM bypass: '+key);
+  if(a.timeout!==undefined)assert(Number.isInteger(a.timeout)&&a.timeout>0&&a.timeout<=45000,'Invalid action timeout');
+  if(a.kind==='leave-return'){assert.equal(phase,'before');assert.equal(pressed,null,'Cannot leave with held input');validateLifecycleAction(a,boundaries);continue;}
+  if(a.kind==='release-boundary'){
+   assert(!Object.hasOwn(a,'target')&&!Object.hasOwn(a,'value'),'Boundary release only names its declared boundary');
+   const b=boundaries.find(b=>b.id===a.boundaryId);assert(b&&b.outcome.kind==='hold'&&b.outcome.release,'Declared releasable held boundary required');
+   assert(!released.has(a.boundaryId),'Duplicate boundary release');released.add(a.boundaryId);continue;
+  }
+  assert(typeof a.target==='string' && a.target.trim(),'Semantic target required');
+  if(a.kind==='input')assert.equal(typeof a.value,'string','Input requires raw string value');
+  else assert(!Object.hasOwn(a,'value'),'Only input accepts value');
+  if(phase==='after')assert.equal(a.kind,'release','Only normal release follows target assertions');
+  if(a.kind==='wait-state')assert(['visible','hidden','enabled','disabled'].includes(a.state),'Unknown semantic state');
+  if(a.timeout!==undefined)assert(Number.isInteger(a.timeout)&&a.timeout>0&&a.timeout<=45000,'Invalid action timeout');
+  if(a.boundaryId)assert(boundaries.some(b=>b.id===a.boundaryId),'Unknown action boundary');
+  if(a.kind==='press'){assert.equal(pressed,null,'Press must release before next press');pressed={target:a.target,instance:a.instance};assert(!a.boundaryId,'Navigation belongs to release, not press');}
+  if(a.kind==='release'){assert.deepEqual({target:a.target,instance:a.instance},pressed,'Release must match a press');pressed=null;}
+ }
+ assert.equal(pressed,null,'Press requires declared release');
+}
+export function targetActions({page,locate,synchronize,boundary,receipts=[],observeInput,beforePress}) {
+ let held=null;
+ async function waitBoundary(id,timeout){
+  const row=()=>boundary.evidence().expectations.find(r=>r.id===id);
+  assert(row(),'Declared boundary required');await expect.poll(()=>row().received,{timeout}).toBe(row().times);
+  if(row().outcome.kind!=='hold'||row().released){
+   await expect.poll(()=>row().delivered,{timeout}).toBe(row().times);
+   if(row().requireConsumption)await expect.poll(()=>row().consumed,{timeout}).toBe(row().times);
+  }
+ }
+ async function release(){assert(held,'No pressed input');await page.mouse.up();held=null;}
+ const pendingReleases=new Map();
+ return {
+  async releaseHeldSnapshot(action){
+   // No synchronization, DOM sampling, screenshots or boundary wait before native up.
+   assert.equal(action.kind,'release');assert.equal(held?.target,action.target);assert.equal(held?.instance,action.instance);
+   const receipt={id:action.id,kind:action.kind,target:action.target,status:'released-awaiting-boundary',protocol:'immediate-native-up-before-node-validation'};
+   receipts.push(receipt);await release();pendingReleases.set(action.id,receipt);return receipt;
+  },
+  async completeHeldRelease(action){
+   const receipt=pendingReleases.get(action.id);assert(receipt,'Original immediate release required');
+   try{if(action.boundaryId)await waitBoundary(action.boundaryId,action.timeout??10000);receipt.status='passed';}
+   catch(error){receipt.status='failed';receipt.error=error.message;throw error;}
+   finally{pendingReleases.delete(action.id);}
+  },
+  async run(action){
+   const timeout=action.timeout??10000;
+   const receipt={id:action.id,kind:action.kind,target:action.target,status:'running'};receipts.push(receipt);
+   try{
+    await synchronize?.();
+    if(action.kind==='release-boundary'){
+     await boundary.releaseBoundary(action.boundaryId);await waitBoundary(action.boundaryId,timeout);receipt.status='passed';return;
+    }
+    const locator=locate(action.target,action.instance);
+    if(action.kind==='wait-state'){
+     if(action.state==='hidden'){
+      await expect.poll(async()=>{const n=await locator.count();assert(n<=1,'Duplicate semantic target');return n===0||!await locator.isVisible();},{timeout}).toBe(true);
+     }else {await expect(locator).toHaveCount(1,{timeout});
+      if(action.state==='visible')await expect(locator).toBeVisible({timeout});
+      else await waitNativeEnabled(locator,action.state==='enabled',{timeout});}
+    }else if(action.kind==='release'){
+     await observeInput?.('before-release',action);
+     assert.equal(held?.target,action.target,'Release target mismatch');assert.equal(held?.instance,action.instance,'Release source instance mismatch');await release();await observeInput?.('after-release',action);
+    }else {
+     await expect(locator).toHaveCount(1,{timeout});await expect(locator).toBeVisible({timeout});await waitNativeEnabled(locator,true,{timeout});
+     await locator.scrollIntoViewIfNeeded({timeout});await waitForNativeInput(page,locator,{timeout});
+     if(['input','focus','blur','clear'].includes(action.kind)){
+      assert(!held,'Cannot edit while pressed');
+      const native=await editableCarrier(locator,timeout);
+      receipt.before=await editableState(native);
+      if(action.kind==='input')await native.fill(action.value,{timeout});
+      else if(action.kind==='clear')await native.fill('',{timeout});
+      else if(action.kind==='focus')await native.focus({timeout});
+      else {
+       // A browser Tab transfers focus through the real native keyboard path.
+       await native.focus({timeout});await native.press('Tab',{timeout});
+       await expect(native).not.toBeFocused({timeout});
+      }
+      receipt.after=await editableState(native);
+     }else if(action.kind==='click'){assert(!held,'Cannot click while pressed');await locator.click({timeout});}
+     else {assert.equal(action.kind,'press');assert(!held,'Already pressed');await beforePress?.();const box=await locator.boundingBox();assert(box,'Press target requires native box');
+      const x=box.x+box.width/2,y=box.y+box.height/2;await page.mouse.move(x,y);held={target:action.target,instance:action.instance,x,y,pageUrl:page.url(),frameUrl:await locator.evaluate(()=>location.href)};receipt.page={url:held.pageUrl,frameUrl:held.frameUrl};await page.mouse.down();receipt.point={x,y};await observeInput?.('after-press',action);}
+    }
+    if(action.boundaryId)await waitBoundary(action.boundaryId,timeout);
+    receipt.status='passed';
+   }catch(error){receipt.status='failed';receipt.error=error.message;throw error;}
+  },
+  async cleanup(){if(held){const target=held.target;await release();receipts.push({id:'$cleanup-release',kind:'release',target,status:'passed'});}},
+  async cancelForArtifact(clip){
+   assert(held,'Artifact cancellation requires actual held input');
+   const viewport=page.viewportSize(),candidates=[{x:0,y:0},{x:viewport.width-1,y:viewport.height-1}],point=candidates.find(p=>p.x<clip.x||p.y<clip.y||p.x>=clip.x+clip.width||p.y>=clip.y+clip.height);
+   assert(point,'A point outside the captured device is required for native cancellation');
+   const target=held.target;await page.mouse.move(point.x,point.y);await release();
+   receipts.push({id:'$artifact-cancel',kind:'cancel',target,point,protocol:'native-move-outside-device-then-up',status:'passed'});
+  },
+ };
+}
+
+// Resolve only the anchored native editor or its unique native descendant.
+// Case data cannot supply CSS, JS, or an alternative candidate policy.
+export async function editableCarrier(locator,timeout=10000){
+ const own=await locator.evaluate(el=>el.matches('input:not([type=hidden]),textarea,[contenteditable=true]'));
+ const native=own?locator:locator.locator('input:not([type=hidden]),textarea,[contenteditable=true]');
+ await expect(native).toHaveCount(1,{timeout});await expect(native).toBeVisible({timeout});
+ await expect(native).toBeEditable({timeout});return native;
+}
+async function editableState(locator){
+ return locator.evaluate(el=>({value:'value' in el?el.value:el.textContent,focused:el.ownerDocument.activeElement===el}));
+}

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

@@ -0,0 +1,125 @@
+"""Concurrency controls use stub runtimes, never business coverage or SDK startup."""
+import importlib.util
+import json
+from pathlib import Path
+import signal
+import sys
+import tempfile
+import threading
+import unittest
+from unittest.mock import patch
+
+spec = importlib.util.spec_from_file_location('batch', Path(__file__).with_name('run-batch.py'))
+batch = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(batch)
+
+
+class StubWorkers:
+    """Only replace worker subprocesses; execute the real scheduler and certification."""
+    def __init__(self, expected):
+        self.barrier = threading.Barrier(expected)
+        self.lock = threading.Lock()
+        self.active = self.peak = self.launched = 0
+
+    def __call__(self, command, **kwargs):
+        owner = self
+        with self.lock:
+            self.active += 1
+            self.launched += 1
+            self.peak = max(self.peak, self.active)
+            number = self.launched
+        class Process:
+            def poll(self): return None
+            def send_signal(self, signum): pass
+            def wait(self):
+                if number <= owner.barrier.parties: owner.barrier.wait(timeout=5)
+                rows = json.loads(Path(command[command.index('--independent-case-list')+1]).read_text())
+                out = Path(command[command.index('--report-dir')+1]); out.mkdir()
+                (out/'batch-results.json').write_text(json.dumps([dict(row, status='passed') for row in rows]))
+                (out/'lifecycle.json').write_text(json.dumps(dict(inputsVerified=True, children=[dict(returncode=0)], control='stub-runtime')))
+                (out/'network-lifecycle.json').write_text(json.dumps(dict(namespaceCleanup=dict(remaining=[]), children=[dict(returncode=0)], control='stub-runtime')))
+                with owner.lock: owner.active -= 1
+                return 0
+        return Process()
+
+
+def fixture(root, count):
+    project = root/'project'; project.mkdir()
+    (project/'plugins').mkdir()
+    config = project/'config.json'
+    config.write_text(json.dumps(dict(schemaVersion=1, repositoryRoot='.', pageRoute='stub/page', pluginSource='plugins', localComponentPackages=[])))
+    product = root/'product'; product.mkdir(); (product/'source').write_text('stub product')
+    sdk = root/'sdk/node_modules/.bin'; sdk.mkdir(parents=True); (sdk/'minifish2').write_text('stub')
+    rows = []
+    for i in range(count):
+        package = root/f'case-{i}'
+        (package/'node_modules/.bin').mkdir(parents=True)
+        for name in ('playwright.config.mjs','package.json','package-lock.json','node_modules/.bin/playwright'):
+            (package/name).write_text('{}')
+        (package/'case.spec.mjs').write_text('\nexport const plan = {};\ntest(plan.case.id,')
+        rows.append(dict(id=str(i), package=str(package)))
+    manifest = root/'manifest.json'; manifest.write_text(json.dumps(rows))
+    return ['--project-root',str(project),'--config',str(config),'--manifest',str(manifest),
+            '--product',str(product),'--node-modules',str(sdk.parents[0]),'--report-dir',str(root/'report')]
+
+
+class ConcurrencyControls(unittest.TestCase):
+    def execute(self, options, count, expected, reason=None, plugins=False):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp); argv = fixture(root,count)+options
+            if plugins:
+                mapping = {str(i): str(root / ('artifact-a' if i < count//2 else 'artifact-b')) for i in range(count)}
+                path=root/'plugins.json'; path.write_text(json.dumps(mapping))
+                argv += ['--plugin-artifact-map',str(path)]
+            stub = StubWorkers(expected)
+            old = {sig: signal.getsignal(sig) for sig in (signal.SIGINT, signal.SIGTERM)}
+            try:
+                with patch.object(sys,'argv',['run-batch.py',*argv]), patch.object(batch.subprocess,'Popen',stub), patch('batch_plugin_groups.validate_plugin_artifact',return_value={'plan':{}}):
+                    self.assertEqual(batch.main(),0)
+            finally:
+                for sig,handler in old.items(): signal.signal(sig,handler)
+            self.assertEqual(stub.peak,expected)
+            self.assertEqual(stub.active,0)
+            inp=json.loads((root/'report/batch-input.json').read_text())
+            summary=json.loads((root/'report/batch-summary.json').read_text())
+            policy=summary['concurrencyPolicy']
+            self.assertEqual(policy,inp['concurrencyPolicy'])
+            self.assertEqual(policy['defaultWorkers'],8)
+            self.assertEqual(policy['actualConcurrency'],expected)
+            self.assertEqual(summary['concurrency'],expected)
+            self.assertEqual(policy['workersReason'],reason)
+            self.assertEqual(sum(policy['shardSizes']),count)
+            self.assertEqual(stub.launched,len(policy['shardSizes']))
+            self.assertIn('requestedWorkers',(root/'report/index.html').read_text())
+            return policy
+
+    def test_default_and_explicit_eight_equivalent(self):
+        default=self.execute([],17,8)
+        self.assertEqual(default,self.execute(['--workers','8'],17,8))
+        self.assertEqual(default['requestedWorkers'],8)
+        self.assertEqual(default['shardSizes'],[3,2,2,2,2,2,2,2])
+
+    def test_plugin_tail_sizes_preserved(self):
+        policy=self.execute([],21,8,plugins=True)
+        self.assertEqual(policy['shardSizes'],[3,3,2,2,3,3,3,2])
+
+    def test_few_tasks_cap(self):
+        self.assertEqual(self.execute([],3,3)['requestedWorkers'],8)
+
+    def test_reason_recorded_for_resource_overrides(self):
+        for value,reason in [(1,'capacity: single worker'),(4,'resource limit: four slots'),(9,'stub-only resource experiment')]:
+            with self.subTest(value=value):
+                policy=self.execute(['--workers',str(value),'--workers-reason',' '+reason+' '],18,value,reason)
+                self.assertEqual(policy['requestedWorkers'],value)
+
+    def test_invalid_overrides_launch_no_workers_or_read_inputs(self):
+        for options in [['--workers','4'],['--workers','4','--workers-reason','  '],['--workers','0'],['--workers','17'],['--workers','-1'],['--workers','bogus']]:
+            with self.subTest(options=options), tempfile.TemporaryDirectory() as tmp:
+                root=Path(tmp); argv=fixture(root,1)+options
+                with patch.object(sys,'argv',['run-batch.py',*argv]), patch.object(batch.subprocess,'Popen') as launch, patch.object(batch,'read_cases') as read:
+                    with self.assertRaises(SystemExit) as error: batch.main()
+                    self.assertEqual(error.exception.code,2)
+                    launch.assert_not_called(); read.assert_not_called()
+                    self.assertFalse((root/'report').exists())
+
+if __name__ == '__main__': unittest.main()