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

package/tools/modules/minifish/harness/check-runner-isolation.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Real dual formal-runner acceptance; faults are intentional, no retries."""
+import argparse
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import time
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from network_isolation import namespace_command, namespace_members
+
+p=argparse.ArgumentParser()
+p.add_argument('--project-root',type=Path,required=True)
+p.add_argument('--config',type=Path,required=True)
+p.add_argument('--node-modules',type=Path,required=True)
+p.add_argument('--report-dir',type=Path,required=True)
+p.add_argument('--dev-verbose',action='store_true')
+p.add_argument('--slirp4netns',type=Path)
+p.add_argument('--slirp-library-path',type=Path)
+a=p.parse_args()
+root=a.report_dir.resolve();root.mkdir(parents=True,exist_ok=False)
+control=root/'control';control.mkdir()
+runner=Path(__file__).resolve().parent/'run-platform.py'
+children=[];events=[]
+def event(name,**data):
+    events.append(dict(event=name,at=time.time(),**data))
+    (root/'events.json').write_text(json.dumps(events,indent=2))
+def launch(marker,timeout=180,mode='hold'):
+    work=root/marker
+    cmd=[sys.executable,str(runner),'--project-root',str(a.project_root.resolve()),'--config',str(a.config.resolve()),'--node-modules',str(a.node_modules.resolve()),'--check','isolation','--isolation-marker',marker,'--isolation-control-dir',str(control),'--isolation-mode',mode,'--report-dir',str(work),'--timeout',str(timeout)]
+    if a.dev_verbose:cmd.append('--dev-verbose')
+    for flag, value in [('--slirp4netns', a.slirp4netns), ('--slirp-library-path', a.slirp_library_path)]:
+        if value:cmd.extend([flag,str(value.resolve())])
+    log=(root/f'{marker}.log').open('w')
+    proc=subprocess.Popen(cmd,stdout=log,stderr=log,start_new_session=True)
+    children.append((proc,log,work));event('launched',marker=marker,pid=proc.pid,command=cmd)
+    return proc,work
+def ready(proc,marker):
+    deadline=time.monotonic()+150
+    while not (control/f'{marker}.ready').exists():
+        if proc.poll() is not None:raise RuntimeError(f'{marker} exited {proc.returncode} before ready')
+        if time.monotonic()>deadline:raise TimeoutError(f'{marker} not ready')
+        time.sleep(.1)
+    event('ready',marker=marker)
+def reclaimed(work):
+    lifecycle=json.loads((work/'lifecycle.json').read_text())
+    for child in lifecycle['children']:
+        # Includes surviving grandchildren even when their group leader exited.
+        for stat in Path('/proc').glob('[0-9]*/stat'):
+            try:
+                fields=stat.read_text().rsplit(')',1)[1].split()
+                assert not (int(fields[2])==child['pid'] and fields[0]!='Z'), f'Live process group {child["pid"]}'
+            except FileNotFoundError:pass
+    network=json.loads((work/'network-lifecycle.json').read_text())
+    assert not namespace_members(network['network']['netns']), 'Run namespace still has live services'
+    assert not network['namespaceCleanup']['remaining']
+    for proc in network['children']:
+        assert not Path(f'/proc/{proc["pid"]}').exists(), f'Network helper still exists {proc}'
+    event('reclaimed',directory=str(work),lifecycle=lifecycle)
+    return lifecycle
+passed=False
+try:
+    one,w1=launch('ISOLATION-1');two,w2=launch('ISOLATION-2')
+    ready(one,'ISOLATION-1');ready(two,'ISOLATION-2')
+    assert one.poll() is None and two.poll() is None
+    runtimes=[json.loads((w/'runtime.json').read_text()) for w in (w1,w2)]
+    assert runtimes[0]['network']['netns'] != runtimes[1]['network']['netns']
+    for w in (w1,w2):
+        assert (w/'app/node_modules').is_dir() and not (w/'app/node_modules').is_symlink()
+        assert not (w/'app/node_modules/.cache').is_symlink()
+    event('concurrent',instances=runtimes)
+    one.send_signal(signal.SIGTERM);assert one.wait(timeout=20)!=0
+    reclaimed(w1)
+    assert two.poll() is None
+    alive=subprocess.run(namespace_command(runtimes[1])+['curl','--fail','--max-time','5','-s','-o','/dev/null',runtimes[1]['url']],check=True)
+    event('peer-http-200',network=runtimes[1]['network'])
+    event('peer-survives')
+    (control/'ISOLATION-2.continue').touch()
+    assert two.wait(timeout=30)==0
+    assert reclaimed(w2)['success'] is True
+    assert json.loads((w2/'isolation-result.json').read_text())['passed'] is True
+    fault,wf=launch('FAULT',mode='fault');ready(fault,'FAULT')
+    assert fault.wait(timeout=20)!=0
+    assert reclaimed(wf)['success'] is False
+    short,wt=launch('TIMEOUT',timeout=30);ready(short,'TIMEOUT')
+    assert short.wait(timeout=45)!=0
+    assert 'exceeded 30 seconds' in (root/'TIMEOUT.log').read_text()
+    assert reclaimed(wt)['success'] is False
+    passed=True
+finally:
+    for proc,log,work in children:
+        if proc.poll() is None:
+            proc.send_signal(signal.SIGTERM)
+            try:proc.wait(timeout=20)
+            except subprocess.TimeoutExpired:
+                os.killpg(proc.pid,signal.SIGKILL);proc.wait()
+        log.close()
+    (root/'result.json').write_text(json.dumps({'passed':passed,'events':events,'children':[{'pid':c.pid,'returncode':c.returncode} for c,_,_ in children]},indent=2))
+if not passed:sys.exit(1)
+print('PASS formal runner concurrency, peer survival, intentional fault and timeout reclamation')

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

@@ -0,0 +1,125 @@
+from network_isolation import add_network_arguments, active_namespace, entry
+from runtime_isolation import prepare_dependencies, dev_command, drain_pty
+#!/usr/bin/env python3
+"""Official Minifish component host, built outside the product repository."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import pty
+import re
+import select
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+
+def fingerprint(root):
+    return {str(p.relative_to(root)): hashlib.sha256(p.read_bytes()).hexdigest()
+            for p in sorted(root.rglob('*')) if p.is_file()
+            and not any(part in ('node_modules', '__pycache__', 'dist', '.git') for part in p.relative_to(root).parts)}
+
+
+def main(prepare,sourceRoot,projectRoot,repositoryRoot=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--product', type=Path, required=True)
+    parser.add_argument('--node-modules', type=Path, required=True)
+    parser.add_argument('--report-dir', type=Path, required=True)
+    parser.add_argument('--design-reference', type=Path, required=True)
+    parser.add_argument('--platform-lock-timeout', type=float, default=0, help='Deprecated no-op; no lock is acquired')
+    parser.add_argument('--timeout', type=int, default=240)
+    add_network_arguments(parser)
+    args = parser.parse_args()
+    work = args.report_dir.resolve()
+    if repositoryRoot is None: parser.error('Explicit repositoryRoot required')
+    repository = Path(repositoryRoot).resolve()
+    if not Path(projectRoot).resolve().is_relative_to(repository): parser.error('Project must belong to repositoryRoot')
+    if work == repository or repository in work.parents:
+        parser.error('Reports must be outside source repository')
+    if not active_namespace(work):
+        work.mkdir(parents=True, exist_ok=False)
+    entry(work, args)
+    if not prepare(args.product.resolve(), work):
+        return 2  # expected red: neither build nor browser launched
+    modules = args.node_modules.resolve()
+    cli = modules / '.bin/minifish2'
+    if not cli.is_file():
+        parser.error('Install the existing locked official harness/toolchain dependencies')
+    prepare_dependencies(modules, work / 'app/node_modules')
+    before = fingerprint(sourceRoot)
+    (work / 'test-manifest.json').write_text(json.dumps(before, indent=2))
+    children = []
+    master, slave = pty.openpty()
+    success = False
+    def interrupted(signum, frame):
+        raise InterruptedError(f'Signal {signum}')
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, interrupted)
+    try:
+        with (work / 'platform.log').open('wb') as log, (work / 'check.log').open('wb') as checklog:
+            dev = subprocess.Popen(dev_command(cli, work), cwd=work / 'app', stdin=slave,
+                                   stdout=slave, stderr=slave, start_new_session=True)
+            children.append(dev)
+            os.close(slave)
+            slave = None
+            buffer, sent_web, checker = '', False, None
+            deadline = time.monotonic() + args.timeout
+            while time.monotonic() < deadline:
+                if select.select([master], [], [], .2)[0]:
+                    try:
+                        data = os.read(master, 65536)
+                    except OSError:
+                        data = b''
+                    log.write(data); log.flush()
+                    buffer = (buffer + data.decode('utf8', errors='replace'))[-200000:]
+                plain = re.sub(r'\x1b\[[0-9;]*[A-Za-z]', '', buffer)
+                if not sent_web and 'minifish>' in plain:
+                    os.write(master, b'web\n'); sent_web = True
+                if 'error[Parse]:' in plain or '编译错误' in plain or 'Could not resolve import' in plain:
+                    raise RuntimeError('Official host compilation failed; see platform.log')
+                match = re.search(r"simulator: '([^']+)'", plain)
+                if match and checker is None:
+                    (work / 'runtime.json').write_text(json.dumps({'url': match.group(1), 'devPid': dev.pid, 'at': time.time(), 'network': json.loads(os.environ['MINIFISH_RUN_NETWORK'])}, indent=2))
+                    env = dict(os.environ, MINIFISH_COMPONENT_URL=match.group(1),
+                               MINIFISH_COMPONENT_REPORT_DIR=str(work / 'results'),
+                               MINIFISH_DESIGN_REFERENCE_HTML=str(args.design_reference.resolve()))
+                    checker = subprocess.Popen([str(projectRoot / 'node_modules/.bin/playwright'), 'test',
+                                                '--config', str(sourceRoot / 'playwright.config.mjs')],
+                                               cwd=projectRoot, env=env, stdout=checklog, stderr=checklog,
+                                               start_new_session=True)
+                    children.append(checker)
+                if checker and checker.poll() is not None:
+                    print((work / 'check.log').read_text(), flush=True)
+                    assert before == fingerprint(sourceRoot), 'Test source changed during execution'
+                    if checker.returncode:
+                        raise RuntimeError(f'Component tests failed: {checker.returncode}')
+                    success = True
+                    break
+                if dev.poll() is not None:
+                    drain_pty(master, log)
+                    raise RuntimeError(f'Official dev exited: {dev.returncode}')
+            else:
+                raise TimeoutError('Official host build/check exceeded budget')
+    finally:
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            signal.signal(sig, signal.SIG_IGN)
+        for child in reversed(children):
+            try: os.killpg(child.pid, signal.SIGTERM)
+            except ProcessLookupError: pass
+        for child in reversed(children):
+            try: child.wait(timeout=5)
+            except subprocess.TimeoutExpired: pass
+            try: os.killpg(child.pid, signal.SIGKILL)
+            except ProcessLookupError: pass
+            child.wait()
+        with (work / 'platform.log').open('ab') as final_log:
+            drain_pty(master, final_log)
+        os.close(master)
+        if slave is not None: os.close(slave)
+        (work / 'lifecycle.json').write_text(json.dumps({'success': success,
+            'children': [{'pid': c.pid, 'returncode': c.returncode} for c in children],
+            'cleanup': 'managed process groups terminated and reaped'}, indent=2))
+    return 0

package/tools/modules/minifish/harness/contract-value.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+export function validateContractValue(value, schema, types = {}, location = '$', {request=false,permittedFields=null} = {}) {
+  if(request && schema.nullable === true && value === undefined)return;
+  assert.notEqual(value, undefined, `${location}: field must be present`);
+  if (value === null) { assert.equal(schema.nullable, true, `${location}: null forbidden`); return; }
+  if (schema.type === 'ref') return validateContractValue(value, types[schema.ref], types, location,{request});
+  if (schema.type === 'discriminatedUnion') {
+    const selected = schema.cases[value?.[schema.discriminator.field]];
+    assert.ok(selected, `${location}: unknown or unreachable stage`);
+    const fields=request?Object.assign({},...Object.values(schema.cases).map(branch=>branch.fields)):null;
+    return validateContractValue(value, selected, types, location,{request,permittedFields:fields});
+  }
+  if (schema.type === 'object') {
+    assert.ok(typeof value === 'object' && !Array.isArray(value), `${location}: object required`);
+    if(request)assert.ok(Object.keys(value).every(key=>Object.hasOwn(permittedFields??schema.fields,key)), `${location}: extra request fields`);
+    if(!request)assert.deepEqual(Object.keys(value).sort(), Object.keys(schema.fields).sort(), `${location}: missing/extra fields`);
+    for (const [key, field] of Object.entries(schema.fields)) validateContractValue(value[key], field, types, `${location}.${key}`,{request});
+    if(request&&permittedFields)for(const key of Object.keys(value)){
+      if(Object.hasOwn(permittedFields,key)&&!Object.hasOwn(schema.fields,key)&&value[key]!==null)validateContractValue(value[key],permittedFields[key],types,`${location}.${key}`,{request});
+    }
+  } else if (schema.type === 'array') {
+    assert.ok(Array.isArray(value), `${location}: array required`);
+    value.forEach((item, index) => validateContractValue(item, schema.items, types, `${location}[${index}]`,{request}));
+  } else if (schema.type === 'enum') {
+    assert.ok(schema.values.includes(value), `${location}: enum mismatch`);
+  } else if (schema.type === 'decimal') {
+    assert.ok(typeof value === 'string' && /^-?\d+(?:\.\d{1,2})?$/.test(value), `${location}: exact yuan string required`);
+  } else {
+    assert.equal(typeof value, schema.type, `${location}: ${schema.type} required`);
+    if (schema.type === 'string' && schema.maxUtf8Bytes !== undefined) assert.ok(Buffer.byteLength(value, 'utf8') <= schema.maxUtf8Bytes, `${location}: UTF8 capacity exceeded`);
+  }
+}

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

@@ -0,0 +1,21 @@
+import {AsyncLocalStorage} from 'node:async_hooks';
+const context=new AsyncLocalStorage();
+const allowed=new Set(['NEXT-P7-CONNECTOR','NEXT-PROCESSING-SURFACE','NEXT-INIT-PRECISION','CORE-WIDGET-LENGTH','CORE-WIDGET-BACKGROUND','CORE-P7-MISSING-DECORATION','BOUNDARY-NUMERIC']);
+export function withVisualFailures(failures,action){return context.run(failures,action);}
+export async function deferredVisual(id,action){
+ try{return await action();}catch(error){
+  const failures=context.getStore();
+  const matcher=['NEXT-PROCESSING-SURFACE','CORE-WIDGET-BACKGROUND','CORE-P7-MISSING-DECORATION'].includes(id)?'toBe':'toBeLessThanOrEqual';
+  if(!allowed.has(id)||!failures||error.matcherResult?.name!==matcher)throw error;
+  failures.push({id,message:error.message,stack:error.stack});
+  return undefined;
+ }
+}
+export function visualErrors(failures){return failures.map(x=>new Error(x.id+': '+x.message));}
+
+const boundaryContext=new AsyncLocalStorage();
+export function withBoundaryVisual(enabled,action){return boundaryContext.run(enabled,action);}
+export async function boundaryNumeric(action){
+ if(!boundaryContext.getStore())return action();
+ return deferredVisual('BOUNDARY-NUMERIC',action);
+}

package/tools/modules/minifish/harness/device-prepare.mjs

@@ -0,0 +1,26 @@
+import {expect} from '@playwright/test';
+// Use the official device editor in a separate preparation page. No business request leaves it.
+export async function prepareIPhone16ProDevice(page,url){
+ const boot=await page.context().newPage();
+ await boot.route('**/*',async route=>{
+  const req=route.request(),u=new URL(req.url());
+  if(u.origin===url.origin&&['GET','HEAD'].includes(req.method())&&!/delegate|mobilegw/.test(u.pathname))return route.continue();
+  return route.abort();
+ });
+ try{
+  await boot.goto(url.href);
+  const shell=boot.frameLocator('iframe[name="lyra-integration-web-sdk"]');
+  await shell.getByText('iPhone 13',{exact:true}).click();
+  await shell.getByText('新增设备',{exact:true}).click();
+  await shell.locator('#device').fill('iPhone16Pro402x874');
+  await shell.locator('#width').fill('402');await shell.locator('#height').fill('874');await shell.locator('#dpr').fill('3');
+  await shell.getByRole('button',{name:'确 认',exact:true}).click();
+  await expect(shell.getByText('iPhone16Pro402x874',{exact:true}).first()).toBeVisible();
+  const cancel=shell.getByRole('button',{name:'取 消',exact:true});
+  await expect(cancel).toBeHidden();
+  await shell.getByText('iPhone16Pro402x874',{exact:true}).first().click();
+  await shell.getByText('关闭皮肤',{exact:true}).click();
+  await shell.getByText('自适应',{exact:true}).click();
+  await shell.getByRole('option',{name:'100%',exact:true}).click();
+ }finally{await boot.close();}
+}

package/tools/modules/minifish/harness/execution-evidence.mjs

@@ -0,0 +1,37 @@
+import {hostDeviceFixture} from './host-device-fixture.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import assert from 'node:assert/strict';
+export const hash=value=>createHash('sha256').update(value).digest('hex');
+export function executionRole(plan,role='behavior'){
+ assert(['behavior','held-artifact'].includes(role),'Unknown execution role');
+ if(role==='held-artifact'){
+  assert(plan.beforeTarget?.some(a=>a.kind==='press'),'Held artifact requires original press');
+  assert(plan.afterTarget?.length&&plan.afterTarget.every(a=>a.kind==='release'&&a.boundaryId),'Held artifact requires declared release boundaries');
+  assert(!plan.completion?.length,'Artifact cannot skip independent completion actions');
+ }
+ return role;
+}
+export function capturePolicy(plan,role,mode){
+ executionRole(plan,role);assert(['none','failed','all'].includes(mode),'Invalid screenshot mode');
+ if(role==='held-artifact')assert.equal(mode,'all','Artifact requires all screenshots');
+ const held=plan.beforeTarget?.some(a=>a.kind==='press');
+ return {target:mode!=='none'&&(!held||role==='held-artifact'),preflight:role==='held-artifact',independentRequired:held&&role==='behavior'&&mode!=='none'};
+}
+export function needsFailureCapture(policy,mode,result){
+ return mode!=='none'&&(result.errors.length>0||!result.screenshots.length&&!policy.independentRequired);
+}
+export function executionEvidence(plan,role){
+ const declaredRoot=process.env.MINIFISH_CASE_PACKAGE_ROOT;assert(declaredRoot,'Explicit independent case root required');
+ const packageRoot=fs.realpathSync(declaredRoot);
+ const walk=directory=>fs.readdirSync(directory,{withFileTypes:true}).flatMap(item=>item.isDirectory()?walk(path.join(directory,item.name)):[path.relative(packageRoot,path.join(directory,item.name))]);
+ const files=['case.spec.mjs','playwright.config.mjs','package.json','package-lock.json','tool-input.json',...walk(path.join(packageRoot,'runner'))].sort();
+ const toolInput=JSON.parse(fs.readFileSync(path.join(packageRoot,'tool-input.json'),'utf8'));
+ const packageFiles=Object.fromEntries(files.map(f=>[f,hash(fs.readFileSync(path.join(packageRoot,f)))]));
+ const manifest=process.env.MINIFISH_SOURCE_MANIFEST;assert(manifest,'Frozen source manifest required for execution identity');
+ const source=JSON.parse(fs.readFileSync(manifest,'utf8')),product=JSON.parse(fs.readFileSync(path.join(path.dirname(manifest),'product-source-manifest.json'),'utf8'));
+ const sorted=o=>JSON.stringify(Object.fromEntries(Object.entries(o).sort(([a],[b])=>a.localeCompare(b))));
+ const productIdentity=JSON.parse(process.env.MINIFISH_PRODUCT_IDENTITY??'null');assert(productIdentity?.sha256,'Actual product identity required');
+ return {toolIdentity:toolInput.toolIdentity,adapterFiles:toolInput.files.filter(f=>f.kind==='adapter'),hostDeviceFixture,productIdentity,executionId:randomUUID(),executionRole:role,startedAt:new Date().toISOString(),fingerprints:{hostDeviceFixtureSha256:hash(JSON.stringify(hostDeviceFixture)),caseId:plan.case.id,planSha256:hash(JSON.stringify(plan)),sourceSha256:hash(sorted(source.testFiles)),productSha256:hash(sorted(product)),packageSha256:hash(sorted(packageFiles)),dependencyLockSha256:packageFiles['package-lock.json']},packageFiles};
+}

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

@@ -0,0 +1,20 @@
+// Observe only public Mini Program SDK application lifecycle callbacks. Browser
+// visibility, arbitrary onShow, page navigation and private methods are not proof.
+export function assertForegroundCycle(proof){
+ if(!proof?.sdkAvailable||!proof.events?.some(e=>e.type==='appHide')||!proof.events?.some((e,i)=>e.type==='appShow'&&proof.events.slice(0,i).some(p=>p.type==='appHide')))throw Error('Real host foreground cycle unobservable: require public appHide followed by appShow');
+ if(proof.pageNavigation)throw Error('Page navigation is not a foreground cycle');
+}
+export async function installForegroundObservation(page){
+ return page.evaluate(()=>{
+  function find(w){try{if(typeof w.my?.onAppHide==='function'&&typeof w.my?.onAppShow==='function')return w.my;for(let i=0;i<w.frames.length;i++){const api=find(w.frames[i]);if(api)return api;}}catch{}return null;}
+  const events=[];const api=find(window);window.__billForegroundProof={sdkAvailable:!!api,events,pageNavigation:false};
+  if(api){api.onAppHide(()=>events.push({type:'appHide',time:Date.now()}));api.onAppShow(()=>events.push({type:'appShow',time:Date.now()}));}
+  return {sdkAvailable:!!api};
+ });
+}
+export async function browserTabCycle(page){
+ const other=await page.context().newPage();try{await other.goto('data:text/html,<title>Independent browser foreground probe</title>');await other.bringToFront();}finally{await other.close();await page.bringToFront();}
+ // Only an actual SDK callback pair may certify this operation as app lifecycle.
+ await page.evaluate(()=>new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r))));
+ return page.evaluate(()=>({...window.__billForegroundProof,browserVisibility:document.visibilityState}));
+}

package/tools/modules/minifish/harness/header-layout.mjs

@@ -0,0 +1,47 @@
+import {currentPageSelector,activeShellSelector} from './browser.mjs';
+import assert from 'node:assert/strict';
+import {observeRole,assertRole} from './carriers.mjs';
+
+// Locator.boundingBox is in top-level browser CSS pixels, including iframe offsets
+// and simulator scaling. Never compare getBoundingClientRect from different frames.
+export async function observeHeaderLayout({page,institution,nativeTitle,pageFrame,nativeFrame}) {
+ const read=async locator=>{
+  const count=await locator.count();
+  if(count!==1)return {count,box:null};
+  return {count,box:await locator.boundingBox(),visible:await locator.isVisible(),
+   paint:await locator.evaluate(e=>{
+    let opacity=1;for(let p=e;p;p=p.parentElement)opacity*=Number(getComputedStyle(p).opacity);
+    const s=getComputedStyle(e);
+    return {text:e.textContent.trim(),opacity,color:s.color,fontSize:parseFloat(s.fontSize),visibility:s.visibility};
+   })};
+ };
+ return {coordinateSpace:'top-level-browser-css-pixels',institution:await read(institution),
+  nativeTitle:await read(nativeTitle),pageFrame:await read(pageFrame),nativeFrame:await read(nativeFrame),
+  viewport:page.viewportSize(),
+  institutionCarriers:await observeRole([{layer:'institution',locator:institution,boundaries:[pageFrame,nativeFrame]}])};
+}
+export function assertHeaderReadable(evidence,{institutionText,nativeTitleText}) {
+ assert.equal(evidence.coordinateSpace,'top-level-browser-css-pixels','header observation coordinate space missing');
+ for(const name of ['institution','nativeTitle','pageFrame','nativeFrame']){
+  const item=evidence[name];
+  assert(item?.count===1&&item.visible&&item.box,`header observation missing/ambiguous/hidden: ${name}`);
+  assert(['x','y','width','height'].every(k=>Number.isFinite(item.box[k]))&&item.box.width>0&&item.box.height>0,`header geometry missing: ${name}`);
+  assert(item.paint?.opacity>=0.99&&item.paint.visibility==='visible',`header not painted: ${name}`);
+ }
+ const a=evidence.institution,b=evidence.nativeTitle;
+ assert.equal(a.paint.text,institutionText,'institution text unreadable');
+ assert.equal(b.paint.text,nativeTitleText,'native title observation mismatch');
+ assert(a.paint.fontSize>=12&&!/rgba\([^)]*,\s*0\)$/.test(a.paint.color),'institution text not painted/readable');
+ const contains=(outer,inner)=>inner.x>=outer.x-0.5&&inner.y>=outer.y-0.5&&inner.x+inner.width<=outer.x+outer.width+0.5&&inner.y+inner.height<=outer.y+outer.height+0.5;
+ assert(evidence.viewport,'header viewport observation missing');
+ for(const outer of [evidence.pageFrame.box,evidence.nativeFrame.box,{x:0,y:0,...evidence.viewport}])
+  assert(contains(outer,a.box),'institution clipped outside visible frame/viewport');
+ const overlap={width:Math.min(a.box.x+a.box.width,b.box.x+b.box.width)-Math.max(a.box.x,b.box.x),height:Math.min(a.box.y+a.box.height,b.box.y+b.box.height)-Math.max(a.box.y,b.box.y)};
+ assert(!(overlap.width>0&&overlap.height>0),`native navigation overlaps institution in global coordinates: ${JSON.stringify(overlap)}`);
+ assertRole(evidence.institutionCarriers,{role:'institution',text:institutionText});
+ return {overlap};
+}
+export const officialHeaderLocators=(page,{institution,pageRoute})=>({page,institution,
+ nativeTitle:page.frameLocator('iframe[name="lyra-integration-web-sdk"]').locator(activeShellSelector+' .title .container'),
+ nativeFrame:page.locator('iframe[name="lyra-integration-web-sdk"]'),
+ pageFrame:page.frameLocator('iframe[name="lyra-integration-web-sdk"]').locator(currentPageSelector(pageRoute))});

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

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import {sampleNativeMetrics,sampleNativeTextVisibility,sampleNativeStyle,sampleNativePressed,sampleHeldNativeState} from './native-dom-sampling.mjs';
+import {nativeMetricsFrameIdentity} from './independent-visual.mjs';
+import {readNativeSemanticIdentity,matchesNativeSemanticIdentity,validateSemanticInstance} from './semantic-anchor.mjs';
+import {validateNativeTextVisibility} from './semantic-observation.mjs';
+export const heldSnapshotVersion='native-held-snapshot-v1';
+export const officialTapLimitMs=350;
+export function heldSnapshotTargetKey(target,instance){
+ validateSemanticInstance(instance);
+ return JSON.stringify([target,instance===undefined?{unspecified:true}:instance]);
+}
+export function freezeHeldSnapshot(snapshot){for(const value of Object.values(snapshot))if(value&&typeof value==='object')freezeHeldSnapshot(value);return Object.freeze(snapshot);}
+export async function prepareHeldNativeInput(root,spec,locator){
+ spec.frameId=await nativeMetricsFrameIdentity(root.locator(':root'));
+ await locator.evaluate(el=>{
+  const nodes=[el,...el.querySelectorAll('*')];
+  if(nodes.some(n=>!['DIV','SPAN','A'].includes(n.tagName)||getComputedStyle(n).display==='contents'))throw Error('Unsupported held native carrier topology before input');
+ });
+ await installHeldInputTimeline(root);
+}
+export async function installHeldInputTimeline(root){
+ await root.locator(':root').evaluate(el=>{
+  const win=el.ownerDocument.defaultView,key='__seeleHeldTimelineV1';if(win[key])throw Error('Duplicate held input timeline');
+  const events=[];win[key]={events};
+  for(const type of ['mousedown','mouseup','touchstart','touchend','touchcancel','pointercancel','scroll'])el.ownerDocument.addEventListener(type,event=>{events.push({type,time:performance.timeOrigin+performance.now(),trusted:event.isTrusted,x:event.clientX,y:event.clientY,scrollX,scrollY});},{capture:true,passive:true});
+ });
+}
+export async function captureHeldSnapshot(root,spec){
+ const body=`async (root,spec)=>{
+  const metrics=(${sampleNativeMetrics.toString()}),paint=(${sampleNativeTextVisibility.toString()}),style=(${sampleNativeStyle.toString()}),pressed=(${sampleNativePressed.toString()}),state=(${sampleHeldNativeState.toString()}),identity=(${readNativeSemanticIdentity.toString()}),matches=(${matchesNativeSemanticIdentity.toString()});
+  const timeline=root.ownerDocument.defaultView.__seeleHeldTimelineV1;if(!timeline)throw Error('Held timeline must be installed before pressing');
+  const now=()=>performance.timeOrigin+performance.now();const start=timeline.events.find(e=>e.type==='touchstart')??timeline.events.find(e=>e.type==='mousedown');if(!start)throw Error('No actual native down event');
+  let groups;while(true){const elements=[...root.ownerDocument.querySelectorAll('*')];groups=spec.targets.map(target=>({target,nodes:elements.filter(node=>{const id=identity(node);return matches(id,target.target,target.instance);})}));
+   if(groups.every(g=>g.nodes.length)||now()-start.time>=350)break;
+   await new Promise(resolve=>{const timer=setTimeout(resolve,Math.max(0,350-(now()-start.time)));requestAnimationFrame(()=>{clearTimeout(timer);resolve();});});
+  }
+  const captureStartedAt=now();const result={version:spec.version,captureStartedAt,pressAt:start.time,timedOut:groups.some(g=>!g.nodes.length),groups:groups.map(g=>({key:g.target.key,target:g.target.target,instance:g.target.instance,count:g.nodes.length,members:g.nodes.map(node=>{const m=metrics(node);m.frameId=spec.frameId;for(const p of [...m.imagePaints,...m.imagePaintInventory])p.frameId=spec.frameId;m.text=node.textContent.trim();m.styles={...m.styles,...style(node,{keys:g.target.styleKeys})};return {identity:identity(node),state:state(node),active:pressed(node),metrics:m,textPaint:paint(node)};})})),eventsAtSnapshot:timeline.events.slice()};result.snapshotAt=now();return result;
+ }`;
+ return freezeHeldSnapshot(await root.locator(':root').evaluate(Function('return ('+body+')')(),spec));
+}
+export async function readReleasedTimeline(root){return root.locator(':root').evaluate(el=>el.ownerDocument.defaultView.__seeleHeldTimelineV1?.events??[]);}
+export function validateHeldInputTiming(snapshot,events){
+ const down=events.find(e=>e.type==='touchstart')??events.find(e=>e.type==='mousedown');const up=events.find(e=>e.type==='touchend')??events.find(e=>e.type==='mouseup');
+ assert(down&&up,'Native down/up events required');assert(events.some(e=>e.type==='mousedown'&&e.trusted)&&events.some(e=>e.type==='mouseup'&&e.trusted),'Original real native mouse input required');
+ const duration=up.time-down.time;assert(duration>=0&&duration<officialTapLimitMs,'Public input invalid: official 350ms tap eligibility exceeded');
+ assert(snapshot&&!snapshot.timedOut&&snapshot.pressAt===down.time&&snapshot.snapshotAt>=down.time&&snapshot.snapshotAt<=up.time,'Only actual held-time snapshot allowed');
+ assert(!events.some(e=>['touchcancel','pointercancel','scroll'].includes(e.type)),'Native held input cancelled or scrolled');return {eligible:true,holdMs:duration,pressAt:down.time,snapshotAt:snapshot.snapshotAt,releaseAt:up.time,events};
+}
+export function validateFrozenHeldAssertion(snapshot,a,validators){
+ const group=snapshot.groups.find(g=>g.key===heldSnapshotTargetKey(a.target,a.instance));assert(group,'Original semantic snapshot required');
+ validators.validateState({count:group.count,visible:group.members.map(m=>m.state.visible)},a);
+ const observations=[];
+ for(const member of group.members){assert(matchesNativeSemanticIdentity(member.identity,a.target,a.instance),'Original semantic identity and optional instance must match');// Preserve measured :active; declared assertions do not require CSS :active.
+
+  if(a.enabled)assert.equal(member.state.enabled,true,'Original native enabled obligation');validators.validateObservation(member.metrics,a);
+  if(a.textFits)validateNativeTextVisibility(member.textPaint,{selfOverflow:'contain'});observations.push({...member.metrics,...(a.textFits?{textPaint:member.textPaint}:{})});
+ }
+ return {count:group.count,visible:group.members.map(m=>m.state.visible),observations,snapshotVersion:snapshot.version,snapshotAt:snapshot.snapshotAt};
+}
+// The release happens in finally before any Node validator or boundary wait.
+export async function executeHeldSnapshot({root,spec,release,validators,capture=captureHeldSnapshot,readEvents=readReleasedTimeline}){
+ let snapshot,error,releaseReceipt;try{snapshot=await capture(root,spec);}catch(e){error=e;}finally{releaseReceipt=await release(spec.release);}
+ const events=await readEvents(root);let timing;
+ try{if(error)throw error;timing=validateHeldInputTiming(snapshot,events);}catch(e){return {snapshot,releaseReceipt,timing:{eligible:false,reason:e.message,events},assertions:spec.assertions.map(a=>({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'invalidated',error:e.message})),observations:{}};}
+ const assertions=[],observations={};for(const a of spec.assertions){try{observations[a.id]=validateFrozenHeldAssertion(snapshot,a,validators);assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'passed'});}catch(e){assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'failed',error:e.message});}}
+ return {snapshot,releaseReceipt,timing,assertions,observations};
+}

package/tools/modules/minifish/harness/host-device-fixture.mjs

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+export const hostDeviceFixture=Object.freeze({version:'official-host-device-v1',appxUtdid:'minifish-test-host-device-fixed',purpose:'simulator-device-telemetry'});
+// Serialized into the official rendererExtend beforeMount hook. It only fills
+// a missing device identifier; user identity/query/Mock and error callbacks stay intact.
+export function configureHostDeviceMount(params,fixture){
+ if(!params||typeof params!=='object'||Array.isArray(params))throw Error('Official mount parameters required');
+ const launch=params.launchParams;
+ if(launch!==undefined&&launch!==null&&(typeof launch!=='object'||Array.isArray(launch)))throw Error('Official launchParams must be an object');
+ const value=launch?.appxUtdid;
+ if(value!==undefined&&value!==null&&typeof value!=='string')throw Error('Explicit appxUtdid must be a string');
+ const explicit=typeof value==='string'&&value.trim().length>0;
+ return {...params,launchParams:{...launch,appxUtdid:explicit?value:fixture.appxUtdid}};
+}
+export function hostDeviceMountEvidence(params,configured,fixture){
+ return {version:fixture.version,purpose:fixture.purpose,appxUtdid:configured.launchParams.appxUtdid,configurationSource:typeof params.launchParams?.appxUtdid==='string'&&params.launchParams.appxUtdid.trim()?'explicit-launchParams':'default-fixture',launchParamKeys:Object.keys(configured.launchParams).sort()};
+}
+export async function installHostDeviceFixtureEvidence(page){
+ const records=[];
+ await page.exposeBinding('__billHostDeviceFixture',(_source,event)=>{
+  assert.equal(event.version,hostDeviceFixture.version);assert.equal(event.purpose,hostDeviceFixture.purpose);
+  assert(typeof event.appxUtdid==='string'&&event.appxUtdid.trim(),'Actual nonempty host device fixture');
+  assert(['explicit-launchParams','default-fixture'].includes(event.configurationSource));
+  if(event.configurationSource==='default-fixture')assert.equal(event.appxUtdid,hostDeviceFixture.appxUtdid);
+  assert(Array.isArray(event.launchParamKeys)&&event.launchParamKeys.includes('appxUtdid'));
+  records.push(structuredClone(event));
+ });
+ return {evidence:()=>({fixture:hostDeviceFixture,mounts:structuredClone(records)})};
+}

package/tools/modules/minifish/harness/host-language.mjs

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+
+// Mock only the documented public API success result. The simulator still
+// supplies all device/layout fields; no product state or module is accessed.
+export function observeSystemLanguage({language}) {
+ const proxies=new WeakMap(),owner=globalThis.top??globalThis;
+ let delivered=0;
+ const event=value=>owner.__billHostLanguage(value);
+ const params=options=>Object.fromEntries(Object.entries(options??{}).filter(([key])=>!['success','fail','complete'].includes(key)));
+ const navigation=(target,original,args,optionsIndex,successIndex)=>{
+  const options=args[optionsIndex]??{};event({stage:'request',kind:'navigation',params:params(options),afterSystemResponse:delivered});
+  const report=()=>event({stage:'success',kind:'navigation'});
+  if(successIndex!==undefined){const success=args[successIndex];args[successIndex]=function(...values){report();return success?.apply(this,values);};}
+  else {const success=options.success;args[optionsIndex]={...options,success:function(...values){report();return success?.apply(this,values);}};}
+  return original.apply(target,args);
+ };
+ const wrap=api=>{
+  if(!api||typeof api!=='object')return api;
+  if(proxies.has(api))return proxies.get(api);
+  const mock=(result,name)=>{
+   const mocked={...result};
+   if(language===null)delete mocked.language;else mocked.language=language;
+   delivered++;event({kind:'system-response',api:name,original:result,mocked});
+   return mocked;
+  };
+  const proxy=new Proxy(api,{get(target,key){
+   const original=Reflect.get(target,key);
+   if(key==='call'&&typeof original==='function')return function(name,options,success,...rest){
+    if(name==='setNavigationBar')return navigation(target,original,[name,options,success,...rest],1,2);
+    if(name!=='getSystemInfo')return original.call(target,name,options,success,...rest);
+    event({kind:'system-request',api:'my.call(getSystemInfo)',params:params(options)});
+    return original.call(target,name,options,function(result){
+     const mocked=mock(result,'my.call(getSystemInfo)');
+     if(typeof success==='function')return success.call(this,mocked);
+    },...rest);
+   };
+   if(key==='setNavigationBar'&&typeof original==='function')return function(options={}){return navigation(target,original,[options],0);};
+   if(key!=='getSystemInfo'||typeof original!=='function')return original;
+   return function(options={}){
+    event({kind:'system-request',api:'my.getSystemInfo',params:params(options)});
+    const success=options.success;
+    return original.call(target,{...options,success:function(result){
+     const mocked=mock(result,'my.getSystemInfo');
+     if(typeof success==='function')return success.call(this,mocked);
+    }});
+   };
+  }});
+  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 installHostLanguage(page,language='zh-CN'){
+ assert(language===null||typeof language==='string','Host language must be a string or missing (null)');
+ const observations=[],systemRequests=[],navigation=[];
+ await page.exposeBinding('__billHostLanguage',(_source,event)=>{if(event.kind==='system-response')observations.push(event);else if(event.kind==='system-request')systemRequests.push(event);else if(event.kind==='navigation')navigation.push(event);else throw Error('Unknown public host observation');});
+ await page.addInitScript(observeSystemLanguage,{language});
+ return {
+  evidence(){return {boundary:'my.getSystemInfo.success.language',language,observations:[...observations],systemRequests:[...systemRequests],navigation:[...navigation]};},
+  assertObserved(){assert(observations.length>0,'Product did not consume the public host system language API');},
+  assertSystemPlan(plan){
+   assert.equal(systemRequests.length,plan.times,'Exact final public system request count');assert.equal(observations.length,plan.times,'Exact final public system callback count');
+   for(const row of systemRequests)assert.deepEqual(row.params,plan.request.params,'Complete public system request');
+   for(const row of observations){const {language:originalLanguage,...original}=row.original;const {language:mockedLanguage,...mocked}=row.mocked;assert.deepEqual(mocked,original,'Actual device fields preserved');assert.equal(mockedLanguage,plan.outcome.value.language);}
+   const requests=navigation.filter(r=>r.stage==='request');assert.equal(requests.length,1,'Exact final navigation request count');assert.equal(requests[0].afterSystemResponse,plan.times,'Delivered public language response consumed before navigation');
+   assert.equal(navigation.filter(r=>r.stage==='success').length,1,'Exact actual navigation success count');
+  },
+ };
+}