@antprofuse/saddle-islands-tools 0.1.12 → 0.1.14

package/package.json

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

package/tools/adapters/islands/component_reference.py

@@ -0,0 +1,62 @@
+"""Resolve compiled branch locations without inventing component identities.
+
+This resolves source references only; it does not observe or prove product state.
+"""
+from copy import deepcopy
+from tools.modules.minifish.component_index import validate
+
+
+def _locations(row):
+    source = row.get('source', {}).get('file')
+    locations = row.get('locations')
+    if not isinstance(source, str) or not source or not isinstance(locations, list) or not locations:
+        raise ValueError('Complete compiled source locations required')
+    result = []
+    for loc in locations:
+        if loc.get('kind') != 'visualComponent':
+            raise ValueError('Visual component location required')
+        page, path = loc.get('page'), loc.get('componentPath')
+        # Official top-level locations omit componentPath; nested ones include it.
+        if 'componentPath' not in loc:
+            path = [{'component': loc.get('component')}]
+        if not isinstance(page, str) or not page or not isinstance(path, list) or not path:
+            raise ValueError('Complete component path required')
+        for segment in path:
+            if not isinstance(segment, dict) or set(segment)-{'component', 'branch'}:
+                raise ValueError('Unsupported component location segment')
+            if any(not isinstance(value, str) or not value for value in segment.values()) or 'component' not in segment:
+                raise ValueError('Invalid component location segment')
+        if loc.get('component') != path[-1]['component']:
+            raise ValueError('Component name disagrees with compiled path')
+        result.append((source, page, deepcopy(path)))
+    return result
+
+
+def resolve_branch(inventory, index, retired, branch_id):
+    """Bind an exact official branch ID to one cmp and its terminal state.
+
+    All ancestor branch segments are retained. No suffix/name matching or ID
+    reconstruction is allowed. Multiple inconsistent locations fail closed.
+    """
+    active = validate(index, inventory, retired)
+    rows = inventory['targets']
+    branch = next((r for r in rows if r['id'] == branch_id), None)
+    if not branch or branch.get('kind') != 'branch':
+        raise ValueError('Exact official branch reference required')
+    reverse = {source: key for key, source in active.items()}
+    components = [(r, _locations(r)) for r in rows if r.get('kind') == 'component']
+    matches = []
+    for file, page, path in _locations(branch):
+        state = path[-1].pop('branch', None)
+        if state is None:
+            raise ValueError('Branch location has no terminal state')
+        candidates = [r for r, locations in components if (file, page, path) in locations]
+        if len(candidates) != 1:
+            raise ValueError('Branch owner must resolve uniquely by compiled location')
+        matches.append((reverse[candidates[0]['id']], candidates[0]['id'], state))
+    if len(set(matches)) != 1:
+        raise ValueError('Inconsistent branch owner locations')
+    component, source_id, state = matches[0]
+    return {'component': component, 'sourceId': source_id, 'state': state,
+            'branchSourceId': branch_id, 'evidence': 'compiled-location',
+            'observed': False}

package/tools/docs/minifish-testing.md

@@ -41,7 +41,7 @@ Legacy component-host integrations must supply an explicit `repositoryRoot` to `
 
 可选 `carrier` 默认为 `semantic-root`。`source-content-group` 在语义root内对可见文字/图像取最低公共元素祖先；`owned-text-block` 在该组内要求唯一不属于其他语义目标的文字分支。选择与期待样式、class、原型HTML标签无关，候选缺失或歧义明确失败；不适用的拓扑不得借此猜测观察目标。`viewportInsets` 可声明 left/right/top/bottom 到业务frame视口的设计长度，返回采样记录包含原root盒及是否选中root。
 
-按压快照目前只支持 `semantic-root`，其他carrier在按下前拒绝，不能释放后采样冒充按住状态。这是明确能力限制，不能默默降级。内容分组不覆盖背景装饰/无文字无图像部件或Shadow DOM；相应责任另用适用的公开观察合同。
+按压快照支持 `semantic-root` 和 `exclusive-parent`，其他carrier在按下前拒绝，不能释放后采样冒充按住状态。这是明确能力限制，不能默默降级。内容分组不覆盖背景装饰/无文字无图像部件或Shadow DOM；相应责任另用适用的公开观察合同。
 
 ### 全量定义编译门禁
 
@@ -88,3 +88,25 @@ MT使用 `iteration stage-gate` 时必须提供 `--compile-result NEW_EXTERNAL_D
 按压region断言可声明公共 `spatial`：`order: [{above: {target, instance?}, below: {target, instance?}}]` 与 `absent: [{target, instance?}]`。目标使用cmp引用。该版本只支持按压region，其他用法在静态编译及运行输入前拒绝。原有普通区域顺序公共接口保持独立，不静默解释该字段。
 
 公共准备将该字段与项目核心按压合同分开校验；一次held快照同时记录原目标、关系目标的几何及排除目标的计数。补充目标不触发等待出现；释放后只判定冻结观察，错误时仍释放。输入350ms限制不变。关系要求两个唯一可见、非重叠且上方在前的真实载体；排除要求零匹配。缺观察、重复身份、隐藏关系目标及未知声明失败。本控制经过真实浏览器单快照验证，不等同于每个业务小程序已经验收。
+
+
+## 组件引用、源状态与关联载体
+
+`component-index resolve` 沿用 `--inventory`、`--inventory-sha256`、`--index`、`--index-sha256`、`--retired`、`--retired-sha256` 和外部 `--tool-source`，另传 `--source-id` 官方原文。组件返回分配ID；分支根据官方编译locations精确归属到组件并返回 `state`，保留祖先分支。页面、歧义或不完整来源拒绝，不猜测近似匹配。输出 `observed:false` 仅表示源定位，不能充当产品状态证据。
+
+分支断言仍以 `target: "cmp_123abc"` 指定组件，并添加 `componentState: "源分支名"`。产品在同一组件根通过 `data-anchor-state` 声明实际状态，原生 `$$dataset.anchorState` 优先；公共工具独立比较实际声明，编译器只允许该组件正式源中存在的状态。不得为了测试写死预期状态：声明由实际产品状态产生，不驱动业务逻辑。该检查不代替分支的内容、样式、行为断言。缺失/错误状态必须失败；存在性为零的断言不能声称观察到状态。
+
+`visual.carrier: "exclusive-parent"` 观察组件根的直接无锚点父包装。父包装必须仅包含这个元素子节点，不能另有非空文本，不能是document根、body或其他组件。它不成为新组件或新覆盖点；选择过程不依赖预期颜色、尺寸、类名。不符合拓扑就报告不支持，不上溯搜索一个有利节点。普通观察可使用 `nativeMetrics(locator,{carrier:'exclusive-parent'})`，业务几何期望仍来自源。held的visual和spatial引用支持该carrier，随原目标在同一次按压快照采样，释放后纯判定。
+
+每个编译计划由公共编译器绑定冻结配置、源清单、活动/退役索引的Git提交和SHA；项目编译器不得提供或覆盖该合同。目标、动作、空间关系中的组件引用必须属于活动集合。实际运行在每个目标状态检查全部锚点声明均属于活动集合，包括隐藏节点；held使用同一次快照。该能力承接旧路径残留排除，无需为源中已删除对象分配活动ID或维护负ID列表。它不证明无标注节点或错误借用有效ID不存在，也不代替Spec规定的条件隐藏断言。产品静态集合检查及逐点内容/布局覆盖继续执行。
+
+
+分支未出现与组件本身隐藏必须区分。仅检查分支是否出现时使用 `{kind:"component-state", target:"cmp_123abc", componentState:"源分支名", present:false}`；同一组件可处于另一个正式状态而保持可见。公共工具观察唯一组件、实际状态和可见性，未知或缺失状态不能冒充“该分支不存在”。`present:true` 验证当前可见分支。它仍是原case内的断言，不新增平行case；分支内部的具体组件及内容继续独立断言。
+
+### 页面视觉（非组件身份）
+
+`kind: "page-visual"` 保留页面视觉责任，不声明 `target`、`instance` 或组件状态，不进入cmp覆盖计数。期望支持 `fullWidth: true`、`fullHeight: true`、`noHorizontalOverflow: true`、`backgroundColor: "rgb(...)"`，至少声明一项；暂不支持按住阶段。尺寸是业务页视口的完整宽高（含起点），不是宿主壳或某个组件的尺寸。
+
+Owner在项目配置填写 `pageSourceId`，精确引用冻结 `anchorInventory` 中 `kind: page` 的源ID；与已有 `pageRoute` 一并绑定到编译产物。公共编译拒绝未知页面、缺绑定及借用组件身份，执行前拒绝与冻结绑定不同的运行路由。
+
+产品在业务页面唯一根节点声明 `data-page-root="true"`，它是布尔页面载体标记，不是组件ID，不加入 `.registry`。工具在已选择的业务frame内采集该根节点，Minifish原生 `$$dataset.pageRoot` 优先；缺失、重复或非法标记失败。不按期望颜色、尺寸、CSS类猜选根节点。背景取该实际根的计算值，水平溢出同时检查该根和业务文档；运行证据保留源页面绑定与实际几何。测试阶段静态验证声明和绑定，实际渲染结果由产品阶段验证。

package/tools/modules/minifish/checks/package.test.mjs

@@ -17,7 +17,7 @@ async function fixture(){
  await writeFile(path.join(project,'harness/regions/alternate.mjs'),"import {semanticLocator} from '@antprofuse/saddle-islands-tools/tools/modules/minifish/harness/semantic-anchor.mjs';export function locate(root,name){return semanticLocator(root,name)};export function assertTarget(){}");
  return {root,project,configFile,config,loaded:await loadProject(project,configFile)};
 }
-test('alternate project static closure records tool/adapter separately and copies no unrelated region',async()=>{const f=await fixture();try{const output=path.join(f.root,'artifact'),records=await packageRunner(f.loaded,output,'regions/alternate.mjs');assert(records.some(r=>r.kind==='tool'&&r.path==='harness/semantic-anchor.mjs'));for(const name of ['held-spatial.mjs','spatial-contract.mjs','region-order.mjs','visual-expectation.mjs','visual-carrier.mjs','jsapi.mjs','browser.mjs','official-bridge-dispatch.mjs']){assert(records.some(r=>r.kind==='tool'&&r.path==='harness/'+name));assert((await readFile(path.join(output,'tools/harness',name),'utf8')).length>0);}assert(records.some(r=>r.kind==='adapter'&&r.path==='harness/regions/alternate.mjs'));assert(records.every(r=>/^[a-f0-9]{64}$/.test(r.sha256)));assert(!records.some(r=>r.path.includes('T1')));assert((await readFile(path.join(output,'adapters/harness/regions/alternate.mjs'),'utf8')).includes('../../../tools/harness/semantic-anchor.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
+test('alternate project static closure records tool/adapter separately and copies no unrelated region',async()=>{const f=await fixture();try{const output=path.join(f.root,'artifact'),records=await packageRunner(f.loaded,output,'regions/alternate.mjs');assert(records.some(r=>r.kind==='tool'&&r.path==='harness/semantic-anchor.mjs'));for(const name of ['component-membership.mjs','held-spatial.mjs','spatial-contract.mjs','region-order.mjs','visual-expectation.mjs','visual-carrier.mjs','jsapi.mjs','browser.mjs','official-bridge-dispatch.mjs']){assert(records.some(r=>r.kind==='tool'&&r.path==='harness/'+name));assert((await readFile(path.join(output,'tools/harness',name),'utf8')).length>0);}assert(records.some(r=>r.kind==='adapter'&&r.path==='harness/regions/alternate.mjs'));assert(records.every(r=>/^[a-f0-9]{64}$/.test(r.sha256)));assert(!records.some(r=>r.path.includes('T1')));assert((await readFile(path.join(output,'adapters/harness/regions/alternate.mjs'),'utf8')).includes('../../../tools/harness/semantic-anchor.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
 for(const [name,code] of [['unknown package',"import 'fs';"],['dependency traversal',"import '../../outside.mjs';"],['direct DOM',"export const read=root=>root.evaluate(()=>1);"],['dynamic import',"export const read=()=>import('./other.mjs');"]])test(name+' is rejected from the closed observation dependency graph',async()=>{const f=await fixture();try{await writeFile(path.join(f.project,'harness/regions/alternate.mjs'),code);await writeFile(path.join(f.project,'outside.mjs'),'export const leaked=true;');await assert.rejects(packageRunner(f.loaded,path.join(f.root,'artifact'),'regions/alternate.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
 test('symlink aliases, undeclared module, missing config, and package output are rejected',async()=>{const f=await fixture();try{const module=path.join(f.project,'harness/regions/alternate.mjs');await rm(module);await writeFile(path.join(f.project,'harness/other.mjs'),'export const safe=true;');await symlink('../other.mjs',module);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'alias'),'regions/alternate.mjs'),/Symlink/);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'unknown'),'regions/unknown.mjs'),/declared module/);await assert.rejects(loadProject(f.project,path.join(f.project,'missing.json')));await assert.rejects(packageRunner(f.loaded,path.join(f.project,'artifact'),'regions/alternate.mjs'),/outside/);}finally{await rm(f.root,{recursive:true,force:true});}});
 test('generic composition preserves exact preparation and original ID mappings without project names',()=>{const noop=()=>{},policy={validateSemanticTargets:noop,supplementalDefinition:()=>null,officialTitle:()=>false,validatePreparationOverrides:noop,validateFixtureTypes:noop,validateSpecialBoundaries:noop,validateIndependentFixture:noop,validatePacketPlan:noop,validatePluginEvents:noop,validatePluginAssertionIdentity:noop,validateObservationModuleName:noop};const catalog={cases:[{id:'alternate / page / value / content',title:'value'}]},definition={caseId:catalog.cases[0].id,ancestors:['open'],basis:[{path:'alternate/source.yaml'}],preparation:{},assertions:[{id:'value',kind:'text',target:'alternate / page / value',expected:'42',count:1}]},fragment={id:'open',inputs:{query:{key:'42'}},boundaries:[],actions:[{kind:'open-page'}]};const plan=compileCase(catalog,definition,[fragment],policy);assert.deepEqual(plan.inputs,fragment.inputs);assert.deepEqual(plan.assertions,definition.assertions);assert.equal(plan.case.id,definition.caseId);assert.throws(()=>compileCase(catalog,{...definition,ancestors:['unknown']},[fragment],policy),/missing preparation/);});

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

@@ -1,3 +1,4 @@
+import {validatePageVisual} from '../harness/page-visual.mjs';
 import {validateSpatial} from '../harness/spatial-contract.mjs';
 import assert from 'node:assert/strict';
 
@@ -10,12 +11,13 @@ export function sourceComponents(inventory,active,retired){
 }
 // Only actual target assertions count. Actions, sourceTarget, basis and nested
 // strings are never recursively treated as evidence of an executed assertion.
-const kinds=new Set(['region','hidden','visible','text','image','text-visual','button-visual','host-navigation','host-native-ui','carousel-frame']);
+const kinds=new Set(['component-state','region','hidden','visible','text','image','text-visual','button-visual','host-navigation','host-native-ui','carousel-frame']);
 export function assertionComponents(plan){
  assert(Array.isArray(plan?.assertions)&&plan.assertions.length,'Compiled target assertions required');
  const seen=new Set(),components=new Set();
  for(const a of plan.assertions){
   assert(a&&typeof a.id==='string'&&a.id&&!seen.has(a.id),'Unique assertion identity required');seen.add(a.id);
+  if(a.kind==='page-visual'){validatePageVisual(a);assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
   if(a.spatial!==undefined){
    assert(a.kind==='region'&&(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Spatial snapshot currently requires held region assertion');
    validateSpatial(a.spatial);

package/tools/modules/minifish/compiler/build-case.mjs

@@ -1,3 +1,5 @@
+import {validateComponentStates} from '../harness/component-state.mjs';
+import {loadComponentContract} from './component-contract.mjs';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import {readFile,mkdir,writeFile,realpath} from 'node:fs/promises';
@@ -22,7 +24,11 @@ export async function buildCase(file,output,options){
  return buildPlanPackage(plan,output,options);
 }
 export async function buildPlanPackage(plan,output,options){
- const project=await loadProject(options.projectRoot,options.config),identity=await toolIdentity(project.config.toolSource,project.config.toolSourceManifest?path.resolve(project.root,project.config.toolSourceManifest):undefined),destination=await checkOutput(output,project);await mkdir(destination,{recursive:true});
+ const project=await loadProject(options.projectRoot,options.config),identity=await toolIdentity(project.config.toolSource,project.config.toolSourceManifest?path.resolve(project.root,project.config.toolSourceManifest):undefined),destination=await checkOutput(output,project);
+ assert(plan.componentContract===undefined,'Project must not override compiler component contract');
+ plan={...plan,componentContract:await loadComponentContract(project)};
+ validateComponentStates(plan,plan.componentContract);
+ await mkdir(destination,{recursive:true});
  const files=await packageRunner(project,path.join(destination,'runner'),plan.observationModule);
  const body=`// Generated from project definitions; do not edit.\nimport {test} from '@playwright/test';\nexport const plan = ${JSON.stringify(plan,null,2)};\ntest(plan.case.id,async({page},testInfo)=>{const {runMiniappCase}=await import('./runner/independent-case-runner.mjs');await runMiniappCase({page,plan,testInfo});});\n`;
  const artifact=path.join(destination,'case.spec.mjs');await writeFile(artifact,body);

package/tools/modules/minifish/compiler/compile-check.mjs

@@ -1,4 +1,6 @@
-import {sourceComponents,assertionComponents,compareCoverage} from './anchor-coverage.mjs';
+import {validateComponentStates} from '../harness/component-state.mjs';
+import {loadComponentContract} from './component-contract.mjs';
+import {assertionComponents,compareCoverage} from './anchor-coverage.mjs';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import {readFile,realpath,mkdir,writeFile} from 'node:fs/promises';
@@ -38,20 +40,11 @@ export async function compileCheck(options){
  const manifest=await readTracked(options.manifest),catalog=await readTracked(path.resolve(root,config.catalog));
  const parsedManifest=JSON.parse(manifest.bytes),parsedCatalog=JSON.parse(catalog.bytes);
  const rows=activeCases(parsedManifest,parsedCatalog);
- assert(config.anchorInventory?.path&&/^[a-f0-9]{64}$/.test(config.anchorInventory.sha256??''),'Owner-frozen anchorInventory required');
- const inventory=await readTracked(path.resolve(root,config.anchorInventory.path));
- assert.equal(sha(inventory.bytes),config.anchorInventory.sha256,'Source component inventory hash mismatch');
- assert(projectPath.endsWith('/code/minifish-tests'),'Expected business test directory');
- const registryPath=projectPath.slice(0,-'minifish-tests'.length)+'.registry';
- assert(!git('status','--porcelain','--untracked-files=all','--',registryPath),'Registry must be clean');
- const registry={},registryText=[];
- for(const name of ['anchors.jsonc','anchors-retired.jsonc']){
-  const relative=registryPath+'/'+name;
-  assert(git('ls-tree',head,'--',relative).startsWith('100644 '),'Regular committed registry file required');
-  const bytes=execFileSync('git',['-C',repo,'show',head+':'+relative]);
-  registry[name]={path:relative,sha256:sha(bytes)};registryText.push(bytes.toString('utf8'));
- }
- const sourceComponentIds=sourceComponents(JSON.parse(inventory.bytes),...registryText);
+ const componentContract=await loadComponentContract(project);
+ assert.equal(componentContract.head,head,'Component contract candidate mismatch');
+ const inventory=componentContract.inventory;
+ const registry={'anchors.jsonc':componentContract.registry.active,'anchors-retired.jsonc':componentContract.registry.retired};
+ const sourceComponentIds=componentContract.activeComponentIds;
  const adapter=await import(pathToFileURL(await project.resolveAdapter(config.compilerAdapter)).href);
  const definitionRoot=await realpath(path.resolve(root,config.definitions)),results=[];
  for(const row of rows){
@@ -65,6 +58,8 @@ export async function compileCheck(options){
    }
    assert.deepEqual(definition.ancestors,fragments.map(f=>f.id),'Preparation ancestry mismatch');
    const plan=await adapter.compile({projectRoot:root,config,catalog:parsedCatalog,definition,fragments});
+   assert(plan.componentContract===undefined,'Project must not override compiler component contract');
+   validateComponentStates(plan,componentContract);
    const componentIds=assertionComponents(plan);
    results.push({id:row.definition,definition:row.definition,status:'passed',componentIds});
   }catch(e){results.push({id:row.definition,definition:row.definition,status:'failed',error:e.message});}
@@ -73,7 +68,7 @@ export async function compileCheck(options){
  const anchorCoverage=compareCoverage(sourceComponentIds,results.filter(r=>r.status==='passed'));
  const result={schemaVersion:2,kind:'minifish-full-compile',head,projectPath,projectTree:git('rev-parse',head+':'+projectPath),
   manifest:{path:manifest.relative,sha256:sha(manifest.bytes)},catalog:{path:catalog.relative,sha256:sha(catalog.bytes)},
-  anchorInventory:{path:inventory.relative,sha256:sha(inventory.bytes)},anchorCoverage,registry,
+  anchorInventory:inventory,anchorCoverage,registry,componentContract,
   toolIdentity:await toolIdentity(config.toolSource,path.resolve(root,config.toolSourceManifest)),
   total:results.length,passed:results.filter(r=>r.status==='passed').length,failed:results.filter(r=>r.status==='failed').length,
   nonExecutable:(parsedManifest.pending??[]).map(r=>({id:r.sourceCaseId,reason:r.reason})),

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

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,realpath} from 'node:fs/promises';
+import {execFileSync} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+export async function loadComponentContract(project){
+ const {root,config}=project;
+ const repo=await realpath(path.resolve(root,config.repositoryRoot));
+ const git=(...args)=>execFileSync('git',['-C',repo,...args],{encoding:'utf8'}).trim();
+ const head=git('rev-parse','HEAD'),relative=path.relative(repo,root).split(path.sep).join('/');
+ assert(relative&&!relative.startsWith('../')&&relative.endsWith('/code/minifish-tests'),'Business test directory required');
+ const source=config.anchorInventory;
+ assert(source?.path&&/^[a-f0-9]{64}$/.test(source.sha256??''),'Frozen anchor inventory required');
+ const read=async file=>{
+  assert.equal(await realpath(file),file,'Symlink component input forbidden');
+  const name=path.relative(repo,file).split(path.sep).join('/');
+  assert(git('ls-tree',head,'--',name).startsWith('100644 '),'Committed regular component input required');
+  assert(!git('status','--porcelain','--untracked-files=all','--',name),'Component input must be clean');
+  const bytes=execFileSync('git',['-C',repo,'show',head+':'+name]);
+  assert.equal(sha(await readFile(file)),sha(bytes),'Component input differs from candidate');
+  return {path:name,sha256:sha(bytes),bytes};
+ };
+ assert(project.configFile&&project.configFile.startsWith(root+path.sep),'Explicit project config required');
+ const configInput=await read(project.configFile);
+ assert.deepEqual(JSON.parse(configInput.bytes),config,'Project config changed during compilation');
+ const sourcePath=path.resolve(root,source.path);assert(sourcePath.startsWith(root+path.sep),'Inventory escaped project');
+ const inventory=await read(sourcePath);assert.equal(inventory.sha256,source.sha256,'Inventory digest mismatch');
+ const registry=path.resolve(root,'../.registry');
+ const active=await read(path.join(registry,'anchors.jsonc')),retired=await read(path.join(registry,'anchors-retired.jsonc'));
+ const parsedInventory=JSON.parse(inventory.bytes);let page;
+ if(config.pageSourceId!==undefined){
+  assert(typeof config.pageSourceId==='string'&&parsedInventory.targets.some(row=>row.kind==='page'&&row.id===config.pageSourceId),'Configured page must be an exact frozen source page');
+  assert(typeof config.pageRoute==='string'&&config.pageRoute,'Configured product route required');
+  page={sourceId:config.pageSourceId,route:config.pageRoute};
+ }
+ const {activeComponentIds,componentStates,branches}=JSON.parse(execFileSync('python3',[fileURLToPath(new URL('../component_index_bridge.py',import.meta.url))],{input:JSON.stringify({inventory:JSON.parse(inventory.bytes),active:active.bytes.toString(),retired:retired.bytes.toString(),withStates:true}),encoding:'utf8',env:{...process.env,PYTHONDONTWRITEBYTECODE:'1'}}));
+ assert.equal(git('rev-parse','HEAD'),head,'Candidate changed during contract construction');
+ const binding=x=>({path:x.path,sha256:x.sha256});
+ return {schemaVersion:1,head,activeComponentIds,componentStates,branches,...(page?{page}:{}),config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
+}

package/tools/modules/minifish/compiler/config.mjs

@@ -17,7 +17,7 @@ export async function loadProject(projectRoot,configFile){
  const resolveAdapter=async relative=>{const declared=path.resolve(root,relative),actual=await realpath(declared);assert.equal(actual,declared,'Symlink adapter dependency forbidden');assert(adapterRoots.some(r=>actual.startsWith(r+path.sep)),'Adapter dependency escaped declared roots');return actual;};
  assert(config.runtimeAdapters&&typeof config.runtimeAdapters==='object','Explicit runtime adapters required');
  for(const name of ['@minifish/project-runtime','@minifish/project-host'])await resolveAdapter(config.runtimeAdapters[name]);
- return {root,config,adapterRoots,resolveAdapter};
+ return {root,config,configFile:file,adapterRoots,resolveAdapter};
 }
 export async function checkOutput(output,project){
  assert(output,'Explicit output directory required');const destination=path.resolve(output);

package/tools/modules/minifish/component_index.py

@@ -129,7 +129,7 @@ def main(argv, identity):
     import argparse
     from pathlib import Path
     parser=argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('operation',choices=['reconcile','verify','diff'])
+    parser.add_argument('operation',choices=['reconcile','verify','diff','resolve'])
     parser.add_argument('--inventory',type=Path,required=True)
     parser.add_argument('--inventory-sha256',required=True)
     parser.add_argument('--index',type=Path)
@@ -137,6 +137,7 @@ def main(argv, identity):
     parser.add_argument('--retired',type=Path)
     parser.add_argument('--retired-sha256')
     parser.add_argument('--changes',type=Path)
+    parser.add_argument('--source-id')
     parser.add_argument('--output',type=Path)
     args=parser.parse_args(argv)
     def read(path,sha,registry=False):
@@ -154,6 +155,20 @@ def main(argv, identity):
         for file,value in [(args.index,previous),(args.retired,retired)]:
             if file.read_bytes()!=registry_text(value).encode('utf-8'):
                 raise ValueError('Noncanonical registry formatting: '+str(file))
+    if args.operation=='resolve':
+        if previous is None or not args.source_id or args.changes or args.output:
+            raise ValueError('Resolve requires registry and exact source ID, no changes/output')
+        validate(previous,inventory,retired)
+        reverse={value:key for key,value in previous.items()}
+        if args.source_id in reverse:
+            result={'component':reverse[args.source_id],'sourceId':args.source_id,'observed':False}
+        else:
+            from tools.adapters.islands.component_reference import resolve_branch
+            result=resolve_branch(inventory,previous,retired,args.source_id)
+        print(json.dumps(result,ensure_ascii=False))
+        return 0
+    if args.source_id is not None:
+        raise ValueError('Source ID is only accepted by resolve')
     if args.operation=='verify':
         if previous is None or args.changes or args.output: raise ValueError('Verify requires index, no changes or output')
         print(json.dumps({'passed':True,'activeComponents':len(validate(previous,inventory,retired))}))

package/tools/modules/minifish/component_index_bridge.py

@@ -11,4 +11,18 @@ if __name__=='__main__':
     active=parse_registry(request['active'])
     retired=parse_registry(request['retired'])
     validate(active,request['inventory'],retired)
-    print(json.dumps(list(active)))
+    if request.get('withStates'):
+        from tools.adapters.islands.component_reference import resolve_branch
+        states={}
+        branches={}
+        for row in request['inventory']['targets']:
+            if row.get('kind')!='branch':
+                continue
+            resolved=resolve_branch(request['inventory'],active,retired,row['id'])
+            branches[row['id']]=resolved
+            values=states.setdefault(resolved['component'],[])
+            if resolved['state'] not in values:
+                values.append(resolved['state'])
+        print(json.dumps({'activeComponentIds':list(active),'componentStates':states,'branches':branches}))
+    else:
+        print(json.dumps(list(active)))

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

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+
+// Serialized into the business frame or invoked inside the single held snapshot.
+// Dataset is authoritative during AppX updates; synchronized DOM may lag.
+export function sampleDeclaredComponents(root){
+ const declarations=[];
+ for(const node of root.ownerDocument.querySelectorAll('*')){
+  const native=Object.prototype.hasOwnProperty.call(node,'$$dataset');
+  const data=node.$$dataset;
+  const declared=native?!!data&&Object.prototype.hasOwnProperty.call(data,'anchorId'):node.hasAttribute('data-anchor-id');
+  if(!declared)continue;
+  const value=native?data.anchorId:node.getAttribute('data-anchor-id');
+  declarations.push({id:typeof value==='string'?value:null,valid:typeof value==='string'&&value.length>0});
+ }
+ return {declarations};
+}
+
+export function validateComponentMembership(snapshot,active){
+ assert(Array.isArray(active)&&active.length>0,'Frozen active component set required');
+ assert(active.every(x=>typeof x==='string'&&/^cmp_[a-f0-9]{6}$/.test(x)),'Invalid active component ID');
+ const allowed=new Set(active);assert.equal(allowed.size,active.length,'Duplicate active component ID');
+ assert(snapshot&&Array.isArray(snapshot.declarations),'Component membership snapshot required');
+ const unknown=new Set();
+ for(const row of snapshot.declarations){
+  assert(row&&row.valid===true&&typeof row.id==='string'&&row.id.length>0,'Invalid declared component identity');
+  if(!allowed.has(row.id))unknown.add(row.id);
+ }
+ assert.equal(unknown.size,0,'Unexpected component declarations: '+JSON.stringify([...unknown]));
+ return {check:'declared-components-are-active',count:snapshot.declarations.length,
+  observedComponentIds:[...new Set(snapshot.declarations.map(x=>x.id))],
+  limitation:'Unannotated nodes and incorrect reuse of a valid component ID are not proven absent'};
+}

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

@@ -0,0 +1,45 @@
+import {validatePageVisual} from './page-visual.mjs';
+import assert from 'node:assert/strict';
+
+// Serialized independently; the product declaration is observed, never inferred
+// from the expected branch or treated as proof of its content/style obligations.
+export function sampleComponentState(node){
+ const native=Object.prototype.hasOwnProperty.call(node,'$$dataset');
+ const value=native?node.$$dataset?.anchorState:node.getAttribute('data-anchor-state');
+ return {value:typeof value==='string'?value:null,valid:typeof value==='string'&&value.length>0};
+}
+export function assertComponentState(actual,expected){
+ assert(typeof expected==='string'&&expected.length>0,'Nonempty source component state required');
+ assert(actual?.valid===true,'Component state declaration missing or invalid');
+ assert.equal(actual.value,expected,'Observed component state differs from source expectation');
+ return {expected,actual:actual.value};
+}
+export function validateComponentStates(plan,contract){
+ const active=new Set(contract?.activeComponentIds??[]);
+ const reference=ref=>{if(ref?.target!==undefined)assert(active.has(ref.target),'Reference must belong to the frozen active component set');};
+ for(const actions of [plan.actions,plan.beforeTarget,plan.afterTarget,plan.completion])for(const action of actions??[])reference(action);
+ for(const a of plan.assertions??[]){
+  if(a.kind==='page-visual'){validatePageVisual(a);assert(contract.page?.sourceId&&contract.page.route,'Compiler-bound page required');assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
+  reference(a);
+  for(const ref of [...(a.spatial?.absent??[]),...(a.spatial?.order??[]).flatMap(pair=>[pair.above,pair.below])])reference(ref);
+  if(a.kind==='component-state')assert(a.componentState!==undefined,'Branch state required');
+  if(a.componentState===undefined)continue;
+  assert(typeof a.componentState==='string'&&a.componentState.length>0,'Nonempty componentState required');
+  assert(/^cmp_[a-f0-9]{6}$/.test(a.target??''),'Component state requires a component target');
+  assert(contract.componentStates?.[a.target]?.includes(a.componentState),'Component state must belong to its frozen source component');
+  if(a.kind==='component-state')assert(typeof a.present==='boolean','Branch presence requires an explicit boolean');
+  else assert(a.present===undefined,'present is only accepted for component-state');
+  assert(a.kind!=='hidden'&&a.count!==0,'State observation requires an existing component');
+ }
+}
+
+export function assertComponentBranch(snapshot,expected,present,allowed){
+ assert(typeof present==='boolean','Explicit branch presence required');
+ assert(Array.isArray(allowed)&&allowed.includes(expected),'Frozen component states required');
+ assert(snapshot&&Number.isInteger(snapshot.count)&&snapshot.count>=0&&snapshot.count<=1,'Unique component owner required');
+ assert(Array.isArray(snapshot.members)&&snapshot.members.length===snapshot.count,'Complete branch observation required');
+ for(const member of snapshot.members){assert(member.componentState?.valid===true,'Component state declaration missing or invalid');assert(allowed.includes(member.componentState.value),'Observed component state absent from frozen source');}
+ const observed=snapshot.members.some(member=>member.componentState.value===expected&&member.visible===true);
+ assert.equal(observed,present,'Observed branch presence differs from source expectation');
+ return {expected,present,observed,members:snapshot.members};
+}

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

@@ -1,3 +1,7 @@
+import {spatialTarget} from './spatial-contract.mjs';
+import {resolveVisualCarrier} from './visual-carrier.mjs';
+import {sampleComponentState,assertComponentState,assertComponentBranch} from './component-state.mjs';
+import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
 import {validateFrozenSpatial} from './held-spatial.mjs';
 import {assertVisualMetrics} from './visual-expectation.mjs';
 import assert from 'node:assert/strict';
@@ -36,7 +40,7 @@ export async function captureHeldSnapshot(root,spec){
    if(groups.every(g=>g.target.waitForPresence===false||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.target.waitForPresence!==false&&!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;
+  const captureStartedAt=now();const membership=spec.componentContract?(${sampleDeclaredComponents.toString()})(root):undefined;const result={version:spec.version,...(membership?{componentMembership:membership}:{}),captureStartedAt,pressAt:start.time,timedOut:groups.some(g=>g.target.waitForPresence!==false&&!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 selected=(${resolveVisualCarrier.toString()})(node,g.target.carrier??'semantic-root');const m=metrics(selected);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),componentState:(${sampleComponentState.toString()})(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));
 }
@@ -48,14 +52,24 @@ export function validateHeldInputTiming(snapshot,events){
  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){
+export function validateFrozenHeldAssertion(snapshot,a,validators,contract){
  const group=snapshot.groups.find(g=>g.key===heldSnapshotTargetKey(a.target,a.instance));assert(group,'Original semantic snapshot required');
+ if(a.kind==='component-state')return assertComponentBranch({count:group.count,members:group.members.map(m=>({componentState:m.componentState,visible:m.state.visible}))},a.componentState,a.present,contract?.componentStates?.[a.target]);
  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.componentState!==undefined)assertComponentState(member.componentState,a.componentState);
   if(a.enabled)assert.equal(member.state.enabled,true,'Original native enabled obligation');validators.validateObservation(member.metrics,a);
-  if(a.kind==='region'&&a.check==='visual'){assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier not captured');assertVisualMetrics(member.metrics,a.visual);}
+  if(a.kind==='region'&&a.check==='visual'){
+   let visualMetrics=member.metrics;
+   if(a.visual.carrier==='exclusive-parent'){
+    const key=spatialTarget({target:a.target,instance:a.instance,carrier:'exclusive-parent'}).key;
+    const carrier=snapshot.groups.find(g=>g.key===key);assert(carrier?.count===1&&carrier.members.length===1,'Unique frozen visual carrier required');
+    visualMetrics=carrier.members[0].metrics;
+   }else assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier not captured');
+   assertVisualMetrics(visualMetrics,a.visual);
+  }
   if(a.textFits)validateNativeTextVisibility(member.textPaint,{selfOverflow:'contain'});observations.push({...member.metrics,...(a.textFits?{textPaint:member.textPaint}:{})});
  }
  const spatial=a.spatial?validateFrozenSpatial(snapshot,a.spatial):undefined;
@@ -66,6 +80,7 @@ export async function executeHeldSnapshot({root,spec,release,validators,capture=
  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});}}
+ let membership,membershipError;try{if(spec.componentContract)membership=validateComponentMembership(snapshot.componentMembership,spec.componentContract.activeComponentIds);}catch(e){membershipError=e;}
+ const assertions=[],observations={};if(membership)observations.componentMembership=membership;for(const a of spec.assertions){try{if(membershipError)throw membershipError;observations[a.id]=validateFrozenHeldAssertion(snapshot,a,validators,spec.componentContract);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/held-spatial.mjs

@@ -4,10 +4,11 @@ import {validateSpatial,spatialTarget as target} from './spatial-contract.mjs';
 export {validateSpatial} from './spatial-contract.mjs';
 export function prepareHeldWithSpatial(plan,prepareProject){
  const clean=structuredClone(plan);
- for(const a of clean.assertions){if(a.spatial!==undefined)validateSpatial(a.spatial);delete a.spatial;}
+ for(const a of clean.assertions){if(a.spatial!==undefined)validateSpatial(a.spatial);delete a.spatial;delete a.componentState;}
  const result=prepareProject(clean);
  result.assertions=structuredClone(plan.assertions);
  for(const a of plan.assertions){
+  if(a.visual?.carrier==='exclusive-parent'){const t=target({target:a.target,instance:a.instance,carrier:'exclusive-parent'});if(!result.targets.some(existing=>existing.key===t.key))result.targets.push(t);}
   if(!a.spatial)continue;
   const refs=[...(a.spatial.absent??[]),...(a.spatial.order??[]).flatMap(p=>[p.above,p.below])];
   for(const ref of refs){const t=target(ref);if(!result.targets.some(existing=>existing.key===t.key))result.targets.push(t);}

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

@@ -1,3 +1,6 @@
+import {observePageVisual,assertPageRoute} from './page-visual.mjs';
+import {sampleComponentState,assertComponentState,assertComponentBranch,validateComponentStates} from './component-state.mjs';
+import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
 import {prepareHeldWithSpatial} from './held-spatial.mjs';
 import {validateRegionVisualAssertions,assertVisualMetrics} from './visual-expectation.mjs';
 import {hostPolicy} from '@minifish/project-host';
@@ -29,6 +32,10 @@ function target(root, name) { return semanticLocator(root, name); }
 
 export async function runMiniappCase({page, plan, testInfo}) {
   validateRegionVisualAssertions(plan.assertions);
+  validateComponentStates(plan,plan.componentContract);
+  if(plan.assertions.some(a=>a.kind==='page-visual'))assertPageRoute(plan.componentContract.page,process.env.MINIFISH_PAGE_ROUTE);
+  assert(plan.componentContract?.schemaVersion===1,'Compiler-bound component membership contract required');
+  validateComponentMembership({declarations:[]},plan.componentContract.activeComponentIds);
   assert.equal(plan.resources.length, 0, 'resource handling is not implemented in this runner yet');
   const boundary = plan.boundaries.length ? independentBoundary(plan.boundaries) : zeroBusinessPlan();
   const images = installRendererImageEvidence(page);
@@ -59,6 +66,7 @@ export async function runMiniappCase({page, plan, testInfo}) {
     result.preparation = 'running';
     if(!artifactOnly&&plan.assertions.some(a=>a.spatial!==undefined))assert((plan.beforeTarget??[]).some(a=>a.kind==='press'),'Spatial snapshot requires held input');
     if(!artifactOnly&&(plan.beforeTarget??[]).some(a=>a.kind==='press'))heldSpec=prepareHeldWithSpatial(plan,prepareHeldSnapshot);
+    if(heldSpec)heldSpec.componentContract=plan.componentContract;
     if(plan.plugin){
       assert(process.env.MINIFISH_PLUGIN_PACKAGE_URL&&process.env.MINIFISH_PLUGIN_ARTIFACT_MANIFEST,'Explicit compiled plugin artifact required');
       const artifact=JSON.parse(await readFile(process.env.MINIFISH_PLUGIN_ARTIFACT_MANIFEST,'utf8'));
@@ -96,7 +104,7 @@ export async function runMiniappCase({page, plan, testInfo}) {
     assert(app, 'missing real page opening');
     await trace?.attach();
     input=targetActions({page,locate:(name,instance)=>locate(app.root,name,{instance}),synchronize:()=>synchronizeAnchors(app.root),boundary,receipts:result.actions,beforePress:async()=>{if(artifactOnly)capturePreparation=await prepareMiniappCapture(page);},observeInput:async(stage,action)=>trace?.sample(stage,app.root,boundary.evidence(),action)});
-    if(heldSpec)for(const a of plan.assertions)if(a.kind==='region'&&a.check==='visual')assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier requires a supported frozen snapshot contract');
+    if(heldSpec)for(const a of plan.assertions)if(a.kind==='region'&&a.check==='visual')assert(!a.visual.carrier||['semantic-root','exclusive-parent'].includes(a.visual.carrier),'Held visual carrier requires a supported frozen snapshot contract');
     if(heldSpec)await prepareHeldNativeInput(app.root,heldSpec,locate(app.root,heldSpec.press.target,{instance:heldSpec.press.instance}));
     for(const action of plan.beforeTarget??[]){
       if(action.kind==='leave-return'){
@@ -114,9 +122,16 @@ export async function runMiniappCase({page, plan, testInfo}) {
       if(!held.timing.eligible){result.inputValidity='invalid';result.target='invalidated';}
     }else for (const assertion of plan.assertions) {
       await synchronizeAnchors(app.root);
-      const locator=assertion.kind==='host-navigation'?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
+      const locator=['host-navigation','page-visual'].includes(assertion.kind)?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
       try {
-        if(assertion.kind==='host-native-ui'){result.observations[assertion.id]=await assertHostNativeUi(page,app,assertion);
+        result.observations.componentMembership=validateComponentMembership(await app.root.locator(':root').evaluate(sampleDeclaredComponents),plan.componentContract.activeComponentIds);
+        if(assertion.componentState!==undefined&&assertion.kind!=='component-state'){await expect(locator).toHaveCount(1);await expect(locator).toBeVisible();result.observations[assertion.id+':componentState']=assertComponentState(await locator.evaluate(sampleComponentState),assertion.componentState);}
+        if(assertion.kind==='page-visual'){result.observations[assertion.id]=await observePageVisual(app.root,assertion,plan.componentContract.page);
+        }else if(assertion.kind==='component-state'){
+          const count=await locator.count(),members=[];assert(count<=1,'Unique branch owner required');
+          if(count)members.push({componentState:await locator.evaluate(sampleComponentState),visible:await locator.isVisible()});
+          result.observations[assertion.id]=assertComponentBranch({count,members},assertion.componentState,assertion.present,plan.componentContract.componentStates[assertion.target]);
+        }else if(assertion.kind==='host-native-ui'){result.observations[assertion.id]=await assertHostNativeUi(page,app,assertion);
         }else if(assertion.kind==='carousel-frame'){result.observations[assertion.id]=await observeCarousel(app.root,assertion.contract,{urls:assertion.images,records:images.records});
         }else if(assertion.kind==='host-navigation'){result.observations[assertion.id]=await assertHostNavigation(page,app,assertion,plan.hostSystemPlan);
         }else if(assertion.kind==='region'){

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

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

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

@@ -1,10 +1,12 @@
 import assert from 'node:assert/strict';
 const keyOf=(target,instance)=>JSON.stringify([target,instance===undefined?{unspecified:true}:instance]);
 export function spatialTarget(ref){
- assert(ref&&Object.keys(ref).every(k=>['target','instance'].includes(k)),'Unknown spatial target field');
+ assert(ref&&Object.keys(ref).every(k=>['target','instance','carrier'].includes(k)),'Unknown spatial target field');
  assert(/^cmp_[0-9a-f]{6}$/.test(ref.target),'Allocated spatial component reference required');
  assert(ref.instance===undefined||(Number.isSafeInteger(ref.instance)&&ref.instance>=0),'Invalid spatial instance');
- return {...ref,key:keyOf(ref.target,ref.instance),styleKeys:[],waitForPresence:false};
+ assert(ref.carrier===undefined||['semantic-root','exclusive-parent'].includes(ref.carrier),'Unsupported spatial carrier');
+ const key=ref.carrier==='exclusive-parent'?JSON.stringify([ref.target,ref.instance===undefined?{unspecified:true}:ref.instance,ref.carrier]):keyOf(ref.target,ref.instance);
+ return {...ref,key,styleKeys:[],waitForPresence:false};
 }
 export function validateSpatial(spec){
  assert(spec&&Object.keys(spec).every(k=>['order','absent'].includes(k)),'Unknown spatial obligation');

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

@@ -1,6 +1,13 @@
 /** Browser-side, expectation-independent selection inside one semantic root. */
 export function resolveVisualCarrier(root, kind = 'semantic-root') {
   if(kind==='semantic-root')return root;
+  if(kind==='exclusive-parent'){
+    const parent=root.parentElement;
+    const marker=n=>Object.prototype.hasOwnProperty.call(n,'$$dataset')?n.$$dataset?.anchorId:n.getAttribute('data-anchor-id');
+    if(!marker(root)||!parent||['BODY','HTML'].includes(parent.tagName)||marker(parent))throw Error('Exclusive parent requires an unanchored non-document wrapper');
+    if(parent.children.length!==1||parent.firstElementChild!==root||[...parent.childNodes].some(n=>n.nodeType===3&&n.textContent.trim()))throw Error('Wrapper must exclusively own the component root');
+    return parent;
+  }
   if(!['source-content-group','owned-text-block'].includes(kind))throw Error('Unsupported visual carrier');
   const visible=element=>{
     for(let p=element;p;p=p.parentElement){const s=getComputedStyle(p);if(s.display==='none'||s.visibility!=='visible'||Number(s.opacity)===0)return false;}

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

@@ -23,7 +23,7 @@ export function validateVisualExpectation(value) {
   for (const key of Object.keys(value)) assert(top.has(key), `visual: unsupported ${key}`);
   number(value.designWidth,'visual.designWidth');
   assert(value.designWidth > 0,'visual.designWidth must be positive');
-  if(value.carrier!==undefined)assert(['semantic-root','source-content-group','owned-text-block'].includes(value.carrier),'visual: unsupported carrier');
+  if(value.carrier!==undefined)assert(['semantic-root','source-content-group','owned-text-block','exclusive-parent'].includes(value.carrier),'visual: unsupported carrier');
   let checks = 0;
   if(value.viewportInsets!==undefined)checks+=keys(value.viewportInsets,new Set(['left','right','top','bottom']),'visual.viewportInsets',number);
   if (value.text !== undefined) {