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

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

@@ -0,0 +1,14 @@
+"""Explicit project input contract; never infer a business checkout from tool paths."""
+import json
+from pathlib import Path
+
+def load_project(root, file):
+    root, file = Path(root).resolve(), Path(file).resolve()
+    if not file.is_relative_to(root): raise ValueError('Config must belong to explicit project')
+    config = json.loads(file.read_text())
+    if config.get('schemaVersion') != 1: raise ValueError('Explicit supported config required')
+    for name in ['repositoryRoot', 'pageRoute', 'pluginSource', 'localComponentPackages']:
+        if name not in config: raise ValueError('Missing project config: '+name)
+    source = (root / config['pluginSource']).resolve()
+    if not source.is_relative_to(root) or not source.is_dir(): raise ValueError('Declared plugin source required')
+    return config

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

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {expect} from '@playwright/test';
+// Exact property sets of the frozen Islands public test matchers (generate-tests guide).
+export const APPEARANCE_PROPERTIES = Object.freeze(['color', 'font-family', 'font-size', 'font-weight', 'font-style', 'font-stretch', 'font-variant-caps', 'line-height', 'letter-spacing', 'word-spacing', 'text-align', 'text-indent', 'text-transform', 'white-space', 'word-break', 'overflow-wrap', 'text-overflow', 'text-decoration-line', 'text-decoration-style', 'text-decoration-color', 'text-decoration-thickness', 'text-shadow', 'background-color', 'background-image', 'background-position-x', 'background-position-y', 'background-size', 'background-repeat', 'background-origin', 'background-clip', 'background-attachment', 'border-top-style', 'border-right-style', 'border-bottom-style', 'border-left-style', 'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color', 'border-top-left-radius', 'border-top-right-radius', 'border-bottom-right-radius', 'border-bottom-left-radius', 'box-shadow', 'opacity', 'visibility', 'filter', 'mix-blend-mode', 'object-fit', 'object-position']);
+export const BOX_PROPERTIES = Object.freeze(['box-sizing', 'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height', 'aspect-ratio', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width', 'display', 'position', 'top', 'right', 'bottom', 'left', 'z-index', 'float', 'clear', 'overflow-x', 'overflow-y', 'transform', 'transform-origin', 'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis', 'order', 'justify-content', 'align-content', 'align-items', 'align-self', 'row-gap', 'column-gap', 'grid-template-columns', 'grid-template-rows', 'grid-template-areas', 'grid-auto-flow', 'grid-auto-columns', 'grid-auto-rows', 'grid-column-start', 'grid-column-end', 'grid-row-start', 'grid-row-end', 'justify-items', 'justify-self', 'writing-mode', 'direction']);
+async function prepare(locator){
+ await expect(locator).toBeVisible();
+ await locator.evaluate(async el=>{
+  await el.ownerDocument.fonts.ready;
+  for(const animation of el.getAnimations({subtree:true}))animation.pause();
+  const images=[...(el.tagName==='IMG'?[el]:[]),...el.querySelectorAll('img')];
+  for(const img of images){await img.decode();if(!img.naturalWidth)throw Error('Visual image is not decoded');}
+ });
+}
+async function compareStyles(actual,design,properties){
+ const count=await design.count();assert.ok(count>0,'Missing independent design instance');
+ await expect(actual).toHaveCount(count);
+ const records=[];
+ for(let index=0;index<count;index++){
+  const a=actual.nth(index),d=design.nth(index);await prepare(a);await prepare(d);
+  const read=(locator)=>locator.evaluate((el,keys)=>{const style=getComputedStyle(el);return Object.fromEntries(keys.map(key=>[key,style.getPropertyValue(key).trim()]));},properties);
+  const [got,wanted]=await Promise.all([read(a),read(d)]);records.push({index,actual:got,design:wanted});
+  expect(got).toEqual(wanted);
+ }
+ return records;
+}
+export const assertPrototypeAppearance=(actual,design)=>compareStyles(actual,design,APPEARANCE_PROPERTIES);
+export const assertPrototypeBoxStyle=(actual,design)=>compareStyles(actual,design,BOX_PROPERTIES);
+// Each side is measured in its own document viewport CSS pixels. Playwright
+// boundingBox is in the top-level host space and includes iframe offsets/scale.
+export async function documentBox(locator){
+ await expect(locator).toHaveCount(1);await expect(locator).toBeVisible();
+ return locator.evaluate(async el=>{
+  await el.ownerDocument.fonts.ready;
+  const {x,y,width,height}=el.getBoundingClientRect();return {x,y,width,height};
+ });
+}
+export async function relativeDocumentBox(parent,child){
+ await expect(parent).toHaveCount(1);await expect(parent).toBeVisible();
+ await expect(child).toHaveCount(1);await expect(child).toBeVisible();
+ const handle=await child.elementHandle();assert.ok(handle,'Missing relative child');
+ try{return await parent.evaluate(async(el,child)=>{
+  if(el.ownerDocument!==child.ownerDocument||!el.contains(child))throw Error('Relative geometry requires parent and child in the same document');
+  await el.ownerDocument.fonts.ready;
+  const origin=el.getBoundingClientRect(),box=child.getBoundingClientRect();
+  return {x:box.x-origin.x,y:box.y-origin.y,width:box.width,height:box.height};
+ },handle);}finally{await handle.dispose();}
+}
+export async function assertPrototypeGeometry(actual,design,{actualParent,designParent}={}){
+ assert.equal(Boolean(actualParent),Boolean(designParent),'Both relative parents are required');
+ const [actualBox,sourceBox]=await Promise.all(actualParent
+  ?[relativeDocumentBox(actualParent,actual),relativeDocumentBox(designParent,design)]
+  :[documentBox(actual),documentBox(design)]);
+ for(const key of ['x','y','width','height'])expect(Math.abs(actualBox[key]-sourceBox[key]),`Document CSS pixel ${key}: ${actualBox[key]} vs ${sourceBox[key]}`).toBeLessThanOrEqual(0.5);
+ return {actualBox,sourceBox};
+}
+export async function openPrototypeReference(productPage,anchor,{referencePath=process.env.MINIFISH_DESIGN_REFERENCE_HTML,imageUrls=[]}={}){
+ assert.ok(referencePath,'Configure MINIFISH_DESIGN_REFERENCE_HTML from build-prototype-reference.py; missing design cannot pass');
+ const html=await fs.readFile(referencePath,'utf8');
+ const manifest=JSON.parse(await fs.readFile(path.join(path.dirname(referencePath),'manifest.json'),'utf8'));
+ assert.equal(manifest.kind,'frozen-prototype-reference-v1');
+ assert.equal(createHash('sha256').update(html).digest('hex'),manifest.htmlSha256,'Design artifact changed after source build');
+ const viewport=await anchor.evaluate(el=>({width:el.ownerDocument.defaultView.innerWidth,height:el.ownerDocument.defaultView.innerHeight}));
+ assert.ok(viewport.width>0&&viewport.height>0,'Missing fixed product viewport');
+ const context=await productPage.context().browser().newContext({viewport});
+ try{
+  const allowedImages=new Set(imageUrls.map(value=>new URL(value).href)),materialRequests=[];
+  const page=await context.newPage();await page.route('**/*',async route=>{
+   const request=route.request(),allowed=allowedImages.has(request.url())&&request.method()==='GET'&&request.resourceType()==='image';
+   materialRequests.push({url:request.url(),method:request.method(),resourceType:request.resourceType(),action:allowed?'allow-exact-image':'abort'});
+   return allowed?route.fallback():route.abort();
+  });
+  await page.setContent(html,{waitUntil:'load'});await page.evaluate(()=>document.fonts.ready);
+  await page.addStyleTag({content:'*,*::before,*::after{animation:none!important;transition:none!important}'});
+  return {page,viewport,manifest,materialRequests,async point(name,text){
+   const node=page.locator(`[data-visual-point$=" / ${name}"]`);await expect(node).toHaveCount(1);
+   if(text!==undefined)await node.evaluate((el,value)=>{if(el.childElementCount!==0)throw Error('Design text slot is not a unique leaf');el.textContent=value;},text);
+   return node;
+  },close:()=>context.close()};
+ }catch(error){await context.close();throw error;}
+}
+// Callers must enumerate all direct semantic child components from the public source.
+// Selectors may differ between product and Prototype; IDs must describe the same component.
+export async function assertPrototypeChildrenLayout(actual,design,children){
+ assert.ok(children.length>0,'No public direct-child mapping');
+ assert.equal(new Set(children.map(c=>c.point)).size,children.length,'Duplicate semantic child mapping');
+ const count=await design.count();assert.ok(count>0,'Missing independent design parent');await expect(actual).toHaveCount(count);
+ const records=[];
+ for(let index=0;index<count;index++){
+  const a=actual.nth(index),d=design.nth(index);await prepare(a);await prepare(d);
+  const read=(parent,side)=>parent.evaluate((el,mapping)=>{
+   const origin=el.getBoundingClientRect(),entries=[];
+   for(const {point,selector}of mapping)for(const node of el.querySelectorAll(selector)){
+    const rect=node.getBoundingClientRect(),style=getComputedStyle(node);
+    const box=style.display==='none'||style.visibility==='hidden'||!node.getClientRects().length?null:{x:rect.x-origin.x,y:rect.y-origin.y,width:rect.width,height:rect.height};
+    entries.push({point,node,box});
+   }
+   if(new Set(entries.map(e=>e.node)).size!==entries.length)throw Error('Overlapping semantic selectors');
+   // Every mapped component must exist in the independent reference, including hidden carriers.
+   for(const {point}of mapping)if(!entries.some(e=>e.point===point))throw Error('Missing mapped semantic child '+point);
+   const covered=node=>entries.some(e=>e.node===node||e.node.contains(node));
+   const candidates=[...el.querySelectorAll('*')].filter(node=>{
+    if(covered(node))return false;
+    if(node.hasAttribute('data-visual-point'))return true;
+    return !node.children.length&&(node.textContent.trim()||['IMG','INPUT','BUTTON','SELECT','TEXTAREA'].includes(node.tagName));
+   });
+   if(candidates.length)throw Error('Unmapped semantic or content-bearing child');
+   entries.sort((l,r)=>l.node===r.node?0:l.node.compareDocumentPosition(r.node)&Node.DOCUMENT_POSITION_FOLLOWING?-1:1);
+   return entries.map(({point,box})=>({point,box}));
+  },children.map(c=>({point:c.point,selector:c[side]})));
+  const [got,wanted]=await Promise.all([read(a,'actual'),read(d,'design')]);
+  expect(got.map(c=>c.point)).toEqual(wanted.map(c=>c.point));
+  for(let i=0;i<wanted.length;i++){
+   if(!wanted[i].box||!got[i].box){expect(got[i].box).toEqual(wanted[i].box);continue;}
+   for(const key of ['x','y','width','height'])expect(Math.abs(got[i].box[key]-wanted[i].box[key])).toBeLessThanOrEqual(0.5);
+  }
+  records.push({index,actual:got,design:wanted});
+ }
+ return records;
+}

package/tools/modules/minifish/harness/region-order.mjs

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import {semanticLocator,anchorSelector} from './semantic-anchor.mjs';
+import {nativeMetrics} from './independent-visual.mjs';
+export function validateRegionOrder(above,below){
+ for(const box of [above,below])assert([box.x,box.y,box.width,box.height].every(Number.isFinite)&&box.width>0&&box.height>0,'Two painted region boxes required');
+ assert(above.y<below.y,'Source region order');
+ assert(above.y+above.height<=below.y+.25,'Source regions must not overlap');
+ return {above,below,gap:below.y-(above.y+above.height)};
+}
+export async function observeRegionOrder(root,{above,below}){
+ const first=semanticLocator(root,above),second=semanticLocator(root,below);
+ await expect(first).toHaveCount(1);await expect(second).toHaveCount(1);
+ await expect(first).toBeVisible();await expect(second).toBeVisible();
+ return {...validateRegionOrder((await nativeMetrics(first)).box,(await nativeMetrics(second)).box),sourcePaths:{above,below},responsibility:'project-supplemental-layout; excluded from Islands denominator'};
+}

package/tools/modules/minifish/harness/renderer-image-evidence.mjs

@@ -0,0 +1,32 @@
+import crypto from 'node:crypto';
+const collectors=new WeakMap();
+const overrides=new WeakMap();
+export function registerRendererImageEvidence(page,records){if(records===undefined)overrides.delete(page);else overrides.set(page,records);}
+export function rendererImageFrameId(page,frame){return collectors.get(page)?.frameId(frame);}
+export function rendererImageEvidence(page){return overrides.get(page)??collectors.get(page)?.records;}
+// Install before product navigation. Decode original response bytes in their own frame;
+// blob URLs do not issue a second material request.
+export function installRendererImageEvidence(page){
+ if(collectors.has(page))throw Error('Renderer collector already installed');
+ const records=[],pending=new Set(),frameIds=new WeakMap();let nextFrameId=0;
+ const frameId=frame=>{if(!frameIds.has(frame))frameIds.set(frame,++nextFrameId);return frameIds.get(frame);};
+ const listener=response=>{
+  if(response.request().resourceType()!=='image')return;
+  const frame=response.frame(),record={url:response.url(),frame:frame.url(),frameId:frameId(frame),status:response.status(),contentType:response.headers()['content-type'],observedAt:new Date().toISOString()};
+  records.push(record);
+  const job=(async()=>{try{
+   const bytes=await response.body();record.bytes=bytes.length;record.sha256=crypto.createHash('sha256').update(bytes).digest('hex');
+   record.decoded=await frame.evaluate(async({base64,type})=>{
+    const bytes=Uint8Array.from(atob(base64),c=>c.charCodeAt(0));
+    const url=URL.createObjectURL(new Blob([bytes],{type}));
+    try{const image=new Image();image.src=url;await image.decode();return {width:image.naturalWidth,height:image.naturalHeight};}finally{URL.revokeObjectURL(url);}
+   },{base64:bytes.toString('base64'),type:record.contentType});
+   record.decodedAt=new Date().toISOString();
+  }catch(error){record.decodeError=error.message;}})();
+  pending.add(job);job.finally(()=>pending.delete(job));
+ };
+ page.on('response',listener);
+ const collector={records,frameId,async snapshot(){while(pending.size)await Promise.all([...pending]);return structuredClone(records);},close(){page.off('response',listener);collectors.delete(page);overrides.delete(page);}};
+ collectors.set(page,collector);return collector;
+}
+export async function captureRendererImageEvidence(page){const c=collectors.get(page);if(!c)throw Error('Renderer collector not installed before product start');return c.snapshot();}

package/tools/modules/minifish/harness/request-guard.mjs

@@ -0,0 +1,65 @@
+import assert from 'node:assert/strict';
+import {rpcTransportFailure} from './native-rpc-failure.mjs';
+import {validateNativeUiResult} from './native-ui-contract.mjs';
+export function createBoundary(definitions,policy) {
+ const {validate:validateIndependentFixture,validatePlan:validatePacketPlan,comparison,requiresConsumption:requiresSourceConsumption,assertPacketCompletion}=policy;
+ assert(Object.values(policy).every(v=>typeof v==='function'),'Explicit boundary policy required');
+ assert(new Set(definitions.map(d=>d.id)).size===definitions.length,'Duplicate boundary id');
+ validatePacketPlan(structuredClone(definitions));
+ const rows=definitions.map(item=>{assert(Number.isSafeInteger(item.times)&&item.times>0,'Positive exact request count required');validateIndependentFixture(structuredClone(item));return {...structuredClone(item),received:0,delivered:0,consumed:0,cancelled:0,released:false,callbacks:[]};});
+ const requiresConsumption=r=>!!r.requireConsumption||!!requiresSourceConsumption(structuredClone(r));
+ const attempts=[],violations=[],pending=new Map();let closed=false;
+ const effective=r=>r.outcome.kind==='hold'?r.released?r.outcome.release:null:r.outcome;
+ const result=r=>{const answer=effective(r);assert(answer,'Held response not released');return answer.kind==='error'&&!r.request.operation.startsWith('jsapi:')?rpcTransportFailure(answer.value.error,answer.value.errorMessage):structuredClone(answer.value);};
+ const desired=r=>r.outcome.kind==='hold'&&!r.released?0:r.times;
+ // deep equality ignores JSON key ordering, while preserving all actual evidence.
+ const equal=(o,a,b)=>{try{assert.deepEqual(comparison(o,structuredClone(a)),comparison(o,structuredClone(b)));return true;}catch{return false;}};
+ const select=(o,q,predicate)=>rows.find(r=>r.request.operation===o&&predicate(r)&&equal(o,q,r.request.params));
+ return {
+  async receive(operation,request,wire){
+   attempts.push(structuredClone({operation,request,...(wire!==undefined?{wire}:{})}));
+   try {
+    const row=select(operation,request,r=>r.received<r.times);
+    assert(row,`Unexpected operation, parameters or duplicate call: ${operation}`);
+    for(const id of row.after??[]){const prior=rows.find(r=>r.id===id);assert(prior&&prior.delivered===prior.times,`Boundary before required response ${id}`);}
+    assert(!closed,'Boundary is closed');assert(!row.execution,'Official execution cannot receive a Mock response');row.received++;
+    if(row.outcome.kind==='hold')await new Promise((resolve,reject)=>pending.set(row.id,[...(pending.get(row.id)??[]),{resolve,reject,row}]));
+    return result(row);
+   }catch(e){if(e.message!=='Controlled held call cancelled at case cleanup')violations.push(e.message);throw e;}
+  },
+  recordOfficialViolation(message){violations.push(message);throw Error(message);},
+  recordNativeUiRequest(operation,request,wire){try{
+   assert(!closed,'Boundary is closed');const r=select(operation,request,r=>r.execution==='official-ui'&&r.received===0);assert(r,'Unexpected, wrong or duplicate official UI request');
+   for(const id of r.after??[]){const prior=rows.find(r=>r.id===id);assert(prior?.delivered===prior.times,'Official UI before '+id);}
+   r.received++;attempts.push(structuredClone({operation,request,wire,execution:'official-ui'}));return r.id;
+  }catch(e){violations.push(e.message);throw e;}},
+  recordNativeUiResult(operation,request,receipt){try{
+   attempts.push(structuredClone({operation,request,execution:'official-ui-result',receipt}));
+   validateNativeUiResult(receipt);const r=select(operation,request,r=>r.execution==='official-ui'&&r.received===1&&r.delivered===0);assert(r,'Native UI result missing request or duplicated');
+   const actualRequest=attempts.find(a=>a.execution==='official-ui'&&a.operation===operation&&equal(operation,a.request,r.request.params));
+   assert.deepEqual(receipt.officialTarget,actualRequest.wire.officialTarget,'Actual result must belong to the same official host request');
+   r.delivered++;r.officialResult=structuredClone(receipt);
+  }catch(e){violations.push(e.message);throw e;}},
+  recordOfficialRequest(operation,request){try{assert(!closed,'Boundary is closed');const r=select(operation,request,r=>r.execution==='official-scroll'&&r.received===0);assert(r,'Unexpected official scroll request');for(const id of r.after??[]){const prior=rows.find(r=>r.id===id);assert(prior?.delivered===prior.times,'Official scroll before '+id);}r.received++;attempts.push(structuredClone({operation,request,execution:'official-scroll'}));}catch(e){violations.push(e.message);throw e;}},
+  recordOfficialCallback(operation,request,callback){try{const r=select(operation,request,r=>r.execution==='official-scroll'&&r.received===1&&r.delivered===0);assert(r,'Official callback without request or duplicate');assert.equal(callback?.kind,'success','Official scroll success required');assert.deepEqual(callback.value,r.outcome.value,'Actual official scroll result');r.delivered++;r.consumed++;r.callbacks.push(structuredClone(callback));}catch(e){violations.push(e.message);throw e;}},
+  markDelivered(operation,request){try{const r=select(operation,request,r=>r.delivered<r.received&&effective(r)&&!r.cancelled);assert(r,'Unexpected response delivery');r.delivered++;}catch(e){violations.push(e.message);throw e;}},
+  markConsumed(operation,request,callback){try{const r=select(operation,request,r=>r.consumed<r.received&&effective(r)&&!r.cancelled);assert(r,'Unexpected response consumption');const expected=effective(r).kind==='error'||effective(r).value?.$testTransportFailure?'fail':'success';if(r.requireConsumption||callback?.kind)assert.equal(callback?.kind,expected,'Unexpected callback type');r.consumed++;r.callbacks.push(structuredClone(callback??{}));}catch(e){violations.push(e.message);throw e;}},
+  releaseBoundary(id){
+   try{assert(!closed,'Boundary is closed');const r=rows.find(r=>r.id===id),p=pending.get(id);
+    assert(r&&r.outcome.kind==='hold'&&r.outcome.release,'Unknown or unreleasable boundary');
+    assert(!r.released&&!r.cancelled,'Boundary already released or cancelled');assert(p&&r.received===1,'Held invocation not received');
+    r.released=true;pending.delete(id);p[0].resolve();
+   }catch(error){violations.push(error.message);throw error;}
+  },
+  assertPacketComplete(){assertPacketCompletion({violations,expectations:rows});},
+  assertComplete(){assert.deepEqual(violations,[]);for(const r of rows){assert.equal(r.received,r.times,`Missing ${r.id}`);assert.equal(r.delivered,desired(r),`Unexpected delivery state ${r.id}`);if(requiresConsumption(r))assert.equal(r.consumed,desired(r),`Missing public callback ${r.id}`);}},
+  assertArtifactComplete(skipped){
+   assert(Array.isArray(skipped)&&skipped.length&&new Set(skipped).size===skipped.length,'Explicit unique skipped artifact boundaries required');
+   assert(skipped.every(id=>rows.some(r=>r.id===id)),'Unknown skipped artifact boundary');assert.deepEqual(violations,[]);
+   for(const r of rows){if(skipped.includes(r.id)){assert.equal(r.received,0,'Artifact must not perform '+r.id);assert.equal(r.delivered,0);assert.equal(r.consumed,0);}else{assert.equal(r.received,r.times,`Missing ${r.id}`);assert.equal(r.delivered,desired(r));if(requiresConsumption(r))assert.equal(r.consumed,desired(r));}}
+   return {status:'verified',expectations:rows.map(r=>({id:r.id,status:skipped.includes(r.id)?'not-executed-artifact-only':'completed',received:r.received,delivered:r.delivered,consumed:r.consumed})),violations:[...violations]};
+  },
+  evidence(){return structuredClone({attempts,violations,expectations:rows});},
+  close(){closed=true;for(const {reject,row}of [...pending.values()].flat()){row.cancelled++;reject(Error('Controlled held call cancelled at case cleanup'));}pending.clear();},
+ };
+}

package/tools/modules/minifish/harness/request-plan.mjs

@@ -0,0 +1,124 @@
+import assert from 'node:assert/strict';
+function sameJsonValue(left,right,operation,decimalCreateComparison) {
+  try { assert.deepStrictEqual(decimalCreateComparison(operation,left),decimalCreateComparison(operation,right)); return true; } catch { return false; }
+}
+
+function jsonCopy(value) {
+  const encoded = JSON.stringify(value);
+  assert.notEqual(encoded, undefined, 'Wire value must be JSON');
+  const decoded = JSON.parse(encoded);
+  assert.deepStrictEqual(decoded, value, 'Wire value must round-trip without loss');
+  return decoded;
+}
+
+/** Transport adapters must decode their envelope without rewriting business data. */
+export function createRequestPlan(expectations, { purePlatform = false } = {},policy) {
+  assert(policy&&typeof policy.validateExpectation==='function','Explicit request schema policy required');
+  const {isRetiredOperation,comparison:decimalCreateComparison,gatewayRequestComparison}=policy;
+  const ids = new Set();
+  const rows = expectations.map((entry) => {
+    assert.ok(entry.id && !ids.has(entry.id), 'Expectation IDs must be unique');
+    ids.add(entry.id);
+    assert.equal(typeof entry.operation, 'string');
+    if (purePlatform) assert.ok(!isRetiredOperation(entry.operation), 'Retired operation cannot be expected');
+    policy.validateExpectation(entry);
+    const row = {
+      id: entry.id, operation: entry.operation, request: jsonCopy(entry.request),
+      response: jsonCopy(entry.response), after: [...(entry.after ?? [])],
+      held: entry.hold === true, status: 'pending', released: false,
+    };
+    row.delivered=false;row.consumed=false;
+    row.delivery=new Promise(resolve=>{row.onDelivery=resolve;});
+    row.consumption=new Promise(resolve=>{row.onConsumption=resolve;});
+    row.arrival = new Promise((resolve) => { row.onArrival = resolve; });
+    row.release = new Promise((resolve) => { row.onRelease = resolve; });
+    return row;
+  });
+  for (const row of rows) for (const id of row.after) {
+    assert.ok(ids.has(id) && id !== row.id, 'Invalid request dependency');
+  }
+  const visited = new Set();
+  function visit(row, active = new Set()) {
+    assert.ok(!active.has(row.id), 'Cyclic request dependencies');
+    if (visited.has(row.id)) return;
+    const next = new Set(active).add(row.id);
+    for (const id of row.after) visit(rows.find((r) => r.id === id), next);
+    visited.add(row.id);
+  }
+  rows.forEach((row) => visit(row));
+  const attempts = [], violations = [];
+  let closed = false;
+  function get(id) {
+    const row = rows.find((r) => r.id === id);
+    assert.ok(row, `Unknown expectation: ${id}`);
+    return row;
+  }
+  return {
+    async receive(operation, request, wire = null) {
+      let row;
+      try {
+        assert.ok(!closed, 'Request after test boundary closed');
+        const actual = jsonCopy(request);
+        attempts.push({ operation, request: actual, wire: jsonCopy(wire) });
+        if (purePlatform) assert.ok(!isRetiredOperation(operation), `Retired operation forbidden: ${operation}`);
+        row = rows.find((r) => r.status === 'pending' && r.operation === operation
+          && (() => { try {
+            assert.deepStrictEqual(policy.requestComparison(operation,actual),policy.requestComparison(operation,r.request));
+            return true;
+          } catch { return false; } })());
+        assert.ok(row, `Unexpected, mismatched or duplicate request: ${operation}`);
+        for (const id of row.after) assert.equal(get(id).status, 'completed', `Request before ${id} completed`);
+        row.actualRequest=actual;
+        row.status = 'received';
+        row.onArrival();
+        if (row.held) await row.release;
+        assert.ok(!closed, 'Response cancelled during cleanup');
+        row.status = 'completed';
+        return jsonCopy(row.response);
+      } catch (error) {
+        if (row) row.status = 'failed';
+        violations.push(error.message);
+        throw error;
+      }
+    },
+    async waitFor(id, timeoutMs = 5000) {
+      let timer;
+      try {
+        await Promise.race([get(id).arrival, new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`Expected request did not arrive: ${id}`)), timeoutMs);
+        })]);
+      } finally { clearTimeout(timer); }
+    },
+    markDelivered(operation,request) {
+      const row=rows.find(r=>r.status==='completed'&&!r.delivered&&r.operation===operation&&sameJsonValue(r.actualRequest??r.request,request,operation,decimalCreateComparison));
+      assert.ok(row,'Delivery requires a matching completed response');row.delivered=true;row.onDelivery();
+    },
+    markConsumed(operation,request,callback) {
+      const row=rows.find(r=>r.status==='completed'&&!r.consumed&&r.operation===operation&&sameJsonValue(r.actualRequest??r.request,request,operation,decimalCreateComparison));
+      assert.ok(row,'Consumption requires a matching completed response');row.consumed=true;if(callback)row.callback=jsonCopy(callback);row.onConsumption();
+    },
+    async waitForDelivery(id,timeoutMs=10000) {
+      let timer;try{await Promise.race([get(id).delivery,new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error(`Response not delivered: ${id}`)),timeoutMs);})]);}finally{clearTimeout(timer);}
+    },
+    async waitForConsumption(id,timeoutMs=10000) {
+      let timer;try{await Promise.race([get(id).consumption,new Promise((_,reject)=>{timer=setTimeout(()=>reject(Error(`Client callback not consumed: ${id}`)),timeoutMs);})]);}finally{clearTimeout(timer);}
+    },
+    release(id) {
+      const row = get(id);
+      assert.ok(row.held && row.status === 'received' && !row.released, 'Release requires a received held request');
+      row.released = true;
+      row.onRelease();
+    },
+    assertComplete() {
+      assert.deepStrictEqual(violations, [], 'Request violations (even if swallowed by product)');
+      assert.deepStrictEqual(rows.filter((r) => r.status !== 'completed').map((r) => r.id), [], 'Incomplete requests');
+    },
+    evidence() {
+      return jsonCopy({ attempts, violations, expectations: rows.map(({ id, operation, request, status,delivered,consumed,callback }) => ({ id, operation, request, status,delivered,consumed,...(callback?{callback}:{}) })) });
+    },
+    close() {
+      closed = true;
+      for (const row of rows) row.onRelease();
+    },
+  };
+}

package/tools/modules/minifish/harness/response-consumption.mjs

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+
+// Observe only the public platform RPC callback. Arguments and results are passed
+// through unchanged; no product module, page method or business state is read.
+export function observePublicRpcCallbacks(officialPlans = []) {
+ const correlate=!Array.isArray(officialPlans)&&officialPlans.correlate;
+ officialPlans=Array.isArray(officialPlans)?officialPlans:officialPlans.officialPlans;
+ const proxies=new WeakMap();let sequence=0,activeCall=null;
+ const realm={url:String(globalThis.location?.href??'unknown').replace(/\?[^#]*/g,'?[redacted]'),kind:typeof document==='undefined'?'worker':'window'};
+ const trace=event=>{if(!correlate)return;try{Promise.resolve(owner.__billPublicApiTrace(event)).catch(()=>{});}catch{}};
+ const owner=globalThis.top??globalThis;
+ const defer=globalThis.setTimeout.bind(globalThis);
+ const notify=identity=>owner.__billRpcConsumed(identity);
+ const wrap=(api,apiPath='my')=>{
+  if(!api||typeof api!=='object')return api;
+  if(proxies.has(api))return proxies.get(api);
+  const proxy=new Proxy(api,{get(target,key){
+   const original=Reflect.get(target,key);
+   if(key==='ap')return wrap(original,apiPath+'.ap');
+   if(typeof original!=='function'||!['call','rpc','showLoading','hideLoading','makePhoneCall','tradePay','getAuthCode','startApp','exitMiniProgram','exitApp','getGradeInfo','getBackgroundFetchData','pushWindow','redirectTo','alert','showToast','getUserInfo','getStorage','setStorage','addToHomeWithGuideDialog','requestSubscribeMessage','pageScrollTo'].includes(key))return original;
+   return function(...args){
+    const apiName=key==='call'?args[0]:key,options=key==='call'?args[1]:args[0];
+    let identity;
+    if(apiName==='rpc'&&options?.operationType)identity={operation:options.operationType,request:options.requestData};
+    else if(['showLoading','hideLoading','makePhoneCall','tradePay','getAuthCode','startApp','exitMiniProgram','exitApp','getGradeInfo','getBackgroundFetchData','pushWindow','redirectTo','alert','showToast','getUserInfo','getStorage','setStorage','addToHomeWithGuideDialog','requestSubscribeMessage','pageScrollTo'].includes(apiName)){const {success,fail,complete,...request}=options??{};if(request.__appxDomain==='app')delete request.__appxDomain;identity={operation:'jsapi:'+apiName,request};}
+    else return original.apply(this===proxy?target:this,args);
+    if(correlate){identity.correlation={callId:++sequence,parentCallId:activeCall,realm,apiPath:key==='call'?apiPath+'.call:'+apiName:apiPath+'.'+apiName,optionScope:{appxDomainPresent:Object.hasOwn(options??{},'__appxDomain'),appxDomain:options?.__appxDomain??null},at:Date.now(),sourceStack:String(new Error().stack??'').split('\n').slice(1,9).map(s=>s.replace(/\?[^\s)]*/g,'?[redacted]'))};trace({kind:'public-call',...identity});}
+    if(apiName==='pageScrollTo'){
+     const same=(a,b)=>JSON.stringify(Object.keys(a).sort().map(k=>[k,a[k]]))===JSON.stringify(Object.keys(b).sort().map(k=>[k,b[k]]));
+     const row=officialPlans.find(r=>r.request.operation===identity.operation&&same(r.request.params,identity.request));
+     if(!row||row.called){owner.__billOfficialScroll({kind:'violation',message:'Undeclared, wrong or duplicate pageScrollTo'});throw Error('Undeclared, wrong or duplicate pageScrollTo');}
+     row.called=true;const started=owner.__billOfficialScroll({kind:'request',at:Date.now(),identity});let seen=false;
+     const wrapOfficial=(fn,kind)=>typeof fn!=='function'?fn:function(...values){
+      try{return fn.apply(this,values);}finally{
+       const receipt={kind:'callback',at:Date.now(),identity:{...identity,callback:{kind,...(values[0]!==undefined?{value:values[0]}:{}),isError:values[0] instanceof Error,errorMessageFromJS:values[0] instanceof Error?values[0].message:null}}};
+       if(seen)receipt.kind='violation',receipt.message='Duplicate official scroll callback';seen=true;
+       defer(()=>Promise.resolve(started).then(()=>owner.__billOfficialScroll(receipt)),0);
+      }
+     };
+     if(key==='call'){if(args.length>2)args[2]=wrapOfficial(args[2],'success');if(args.length>3)args[3]=wrapOfficial(args[3],'fail');}
+     else{args[0]={...options};if(typeof options?.success==='function')args[0].success=wrapOfficial(options.success,'success');if(typeof options?.fail==='function')args[0].fail=wrapOfficial(options.fail,'fail');}
+     return original.apply(this===proxy?target:this,args);
+    }
+    let notified=false;const consumed=()=>{if(!notified){notified=true;defer(()=>notify(identity),0);}};
+    const callback=(fn,kind)=>typeof fn!=='function'?fn:function(...values){
+     try{return fn.apply(this,values);}finally{
+      // Callback Promise continuations run before the following task. Paint is
+      // observed in the owning window, since official worker globals omit rAF.
+      identity.callback={kind,...(values[0]!==undefined?{value:values[0]}:{}),isError:values[0] instanceof Error,errorMessageFromJS:values[0] instanceof Error?values[0].message:null};
+      trace({kind:'public-callback',...identity});
+      consumed();
+     }
+    };
+    if(key!=='call'){
+     if(typeof options?.success==='function'||typeof options?.fail==='function'){
+      args[0]={...options};if(typeof options.success==='function')args[0].success=callback(options.success,'success');if(typeof options.fail==='function')args[0].fail=callback(options.fail,'fail');
+     }
+    }
+    else {if(args.length>2)args[2]=callback(args[2],'success');if(args.length>3)args[3]=callback(args[3],'fail');}
+    const previous=activeCall;activeCall=identity.correlation?.callId??previous;
+    try{return original.apply(this===proxy?target:this,args);}finally{activeCall=previous;}
+   };
+  }});
+  proxies.set(api,proxy);return proxy;
+ };
+ const descriptor=Object.getOwnPropertyDescriptor(globalThis,'my');
+ if(descriptor&&!descriptor.configurable)throw Error('Public my API cannot be observed');
+ let value=descriptor?.value;
+ Object.defineProperty(globalThis,'my',{configurable:true,enumerable:true,
+  get(){return wrap(descriptor?.get?descriptor.get.call(this):value);},
+  set(next){if(descriptor?.set)descriptor.set.call(this,next);else value=next;}});
+}
+export async function installResponseConsumption(page,plan,diagnostics=null){
+ const enabled=process.env.MINIFISH_CALLBACK_CORRELATION==='1',events=[];let sequence=0;
+ const redact=(value,key='')=>{
+  if(/token|password|credential|secret|authorization|cookie|authCode/i.test(key))return '[redacted]';
+  if(Array.isArray(value))return value.map(v=>redact(v));
+  if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).map(([k,v])=>[k,redact(v,k)]));
+  if(typeof value==='string'&&/url|stack/i.test(key))return value.replace(/\?[^\s)#]*/g,'?[redacted]');
+  return value;
+ };
+ const capture=(kind,value,source)=>{if(!enabled)return null;const event=redact({eventId:++sequence,kind,at:Date.now(),...value,owningFrame:{url:source?.frame?.url?.()??null,name:source?.frame?.name?.()??null}});events.push(event);return event;};
+ await page.exposeBinding('__billPublicApiTrace',(source,event)=>{capture(event.kind,event,source);});
+ await page.exposeBinding('__billRpcConsumed',(source,identity)=>{
+  const event=capture('consumption-notification',{identity},source);
+  try{const result=plan.markConsumed(identity.operation,identity.request,identity.callback);if(event)event.accepted=true;return result;}
+  catch(error){if(event){event.accepted=false;event.rejection=error.message;}throw error;}
+ });
+ const official=plan.evidence().expectations.filter(r=>r.execution==='official-scroll');
+ await page.exposeBinding('__billOfficialScroll',(_source,receipt)=>{
+  diagnostics?.capture('public-scroll-'+receipt.kind,receipt.identity,receipt.at);
+  if(receipt.kind==='request')return plan.recordOfficialRequest(receipt.identity.operation,receipt.identity.request);
+  if(receipt.kind==='callback')return plan.recordOfficialCallback(receipt.identity.operation,receipt.identity.request,receipt.identity.callback);
+  return plan.recordOfficialViolation(receipt.message);
+ });
+ await page.addInitScript(observePublicRpcCallbacks,{officialPlans:official,correlate:enabled});
+ return {transport(wire,frame){capture('transport',{transportId:'transport-'+(sequence+1),wire},{frame});},evidence(){return structuredClone(events);}};
+}
+export async function waitForResponseConsumption(plan,id,timeoutMs=10000,page=null){
+ await plan.waitForDelivery(id,timeoutMs);
+ await plan.waitForConsumption(id,timeoutMs);
+ if(page)await page.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve))));
+ const observation=plan.evidence().expectations.find(row=>row.id===id);
+ assert.equal(observation.delivered,true,'Old response must actually be delivered');
+ assert.equal(observation.consumed,true,'Old response must reach the public client callback and paint barrier');
+}

package/tools/modules/minifish/harness/retained-page-lifecycle.mjs

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import {expect} from '@playwright/test';
+import {platformNavigate} from './navigation.mjs';
+import {localNavigationEvidence} from './local-navigation-evidence.mjs';
+
+export function validateLifecycleAction(action,boundaries){
+ assert.equal(action.kind,'leave-return');
+ assert(typeof action.url==='string'&&/^\/pages\/[\w/-]+(?:\?[^#]*)?$/.test(action.url),'Declared local page route required');
+ assert(!/[?&]__appxPageId=/.test(action.url),'Caller cannot allocate official page identity');
+ for(const key of ['awayBoundaryIds','returnBoundaryIds']){
+  assert(Array.isArray(action[key])&&action[key].length&&new Set(action[key]).size===action[key].length,'Explicit unique '+key);
+  for(const id of action[key])assert(boundaries.some(r=>r.id===id),'Declared lifecycle request required');
+ }
+ assert(!action.awayBoundaryIds.some(id=>action.returnBoundaryIds.includes(id)),'Leaving and returning request batches must be disjoint');
+ assert(!Object.hasOwn(action,'target')&&!Object.hasOwn(action,'value'),'Lifecycle is not a target click or injected value');
+}
+export function validateReturnRequests(before,after,ids){
+ assert(ids.length&&new Set(ids).size===ids.length,'Unique return request IDs');
+ for(const id of ids){const old=before.find(r=>r.id===id),row=after.find(r=>r.id===id);
+  assert(old&&row,'Explicit return boundary');assert.equal(old.received,0,'Return batch must not predate leave');
+  assert.equal(row.received,row.times,'Every return request must actually happen');assert.equal(row.delivered,row.times,'Return result must actually arrive');
+  if(row.requireConsumption)assert.equal(row.consumed,row.times,'Return callback must actually be consumed');
+ }
+ return ids;
+}
+export async function retainedPageRoundTrip({page,app,boundary,action,queryBoundaryIds}){
+ const handle=await app.root.owner().elementHandle();assert(handle,'Current official frame element required');
+ const frame=await handle.contentFrame();await handle.dispose();assert(frame&&!frame.isDetached(),'Live current page required');
+ const originalUrl=frame.url(),document=await frame.evaluateHandle(()=>document);
+ const before=boundary.evidence().expectations;
+ try{
+  await platformNavigate(page,'navigateTo',action.url);
+  assert(!frame.isDetached(),'Leaving must retain the source page instance');
+  const wait=async ids=>{for(const id of ids){const row=()=>boundary.evidence().expectations.find(r=>r.id===id);await expect.poll(()=>row().received).toBe(row().times);if(row().outcome.kind!=='hold'){await expect.poll(()=>row().delivered).toBe(row().times);if(row().requireConsumption)await expect.poll(()=>row().consumed).toBe(row().times);}}};
+  await wait(action.awayBoundaryIds);
+  localNavigationEvidence(page).at(-1).queryBoundaryIds=queryBoundaryIds(action.awayBoundaryIds,boundary.evidence());
+  await platformNavigate(page,'navigateBack');
+  const currentHandle=await app.root.owner().elementHandle();assert(currentHandle,'Returned current frame required');const current=await currentHandle.contentFrame();await currentHandle.dispose();
+  assert.equal(current,frame,'Return must activate the same retained Frame object');assert.equal(frame.url(),originalUrl,'Return must preserve exact public page identity');
+  assert.equal(await document.evaluate(doc=>doc===window.document),true,'Return must retain the original document, not reload or reopen it');
+  await wait(action.returnBoundaryIds);
+  const after=boundary.evidence().expectations;
+  const completed=action.returnBoundaryIds.filter(id=>after.find(r=>r.id===id).outcome.kind!=='hold');
+  if(completed.length)validateReturnRequests(before,after,completed);
+  for(const id of action.returnBoundaryIds){const row=after.find(r=>r.id===id);assert.equal(before.find(r=>r.id===id).received,0,'New return batch required');assert.equal(row.received,row.times);}
+  return {url:originalUrl,sameFrame:true,sameDocument:true,awayBoundaryIds:action.awayBoundaryIds,returnBoundaryIds:action.returnBoundaryIds,completed,held:action.returnBoundaryIds.filter(id=>!completed.includes(id))};
+ }finally{await document.dispose();}
+}

package/tools/modules/minifish/harness/rpc-wire.mjs

@@ -0,0 +1,34 @@
+import { rpcTransportEnvelope } from './native-rpc-failure.mjs';
+import assert from 'node:assert/strict';
+
+// Verified on the official Minifish browser worker, /simulator/mobilegw/rpcProxy.
+export function decodeRpcWire(wire) {
+  assert.ok(wire && typeof wire === 'object' && !Array.isArray(wire));
+  assert.equal(typeof wire.operationType, 'string');
+  assert.ok(wire.operationType.length > 0);
+  assert.ok(Array.isArray(wire.requestData), 'requestData must retain its array envelope');
+  return { operation: wire.operationType, request: wire.requestData, wire };
+}
+
+export function encodeRpcResponse(result) {
+  return { success: true, result: {
+    headers: { 'request-id': 'minifish-blackbox' },
+    data: { resultStatus: 1000, result: JSON.stringify(result) },
+  } };
+}
+
+export async function fulfillRpc(route, plan) {
+  const request = route.request();
+  const headers = {
+    'access-control-allow-origin': request.headers().origin ?? 'null',
+    'access-control-allow-credentials': 'true',
+    'access-control-allow-headers': request.headers()['access-control-request-headers'] ?? 'content-type',
+    'access-control-allow-methods': 'POST, OPTIONS',
+  };
+  if (request.method() === 'OPTIONS') return route.fulfill({ status: 204, headers });
+  assert.equal(request.method(), 'POST');
+  const call = decodeRpcWire(request.postDataJSON());
+  const result = await plan.receive(call.operation, call.request, call.wire);
+  await route.fulfill({ headers, json: rpcTransportEnvelope(result, encodeRpcResponse) });
+  plan.markDelivered(call.operation,call.request);
+}