evomeme 0.1.9 → 0.1.10-beta.13

package/dist/stage-public/baked/bakePilot.js

@@ -0,0 +1,44 @@
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { batchStaticScene } from './sceneAppearance.js';
+
+export function annotateSourceNames(gltf) {
+  gltf.scene.traverse(object => {
+    const index = gltf.parser.associations.get(object)?.nodes;
+    if (index !== undefined) object.userData.canonicalSourceName = gltf.parser.json.nodes[index].name;
+  });
+}
+
+export async function loadBakePilot(manifest, readVerified, renderer) {
+  if (manifest.schema !== 'evomeme.cycles_bake_pilot.v1' || manifest.display.runtime_tone_mapped !== false || manifest.display.runtime_lighting !== false) throw new Error('Unsupported bake display contract');
+  const model = await readVerified('runtime/bake-pilot/pilot.glb');
+  const gltf = await new GLTFLoader().parseAsync(model, '');
+  const textures = new Map();
+  try {
+    for (const group of manifest.groups) {
+      const bytes = await readVerified(group.display_texture);
+      const url = URL.createObjectURL(new Blob([bytes], { type: 'image/png' }));
+      let texture;
+      try { texture = await new THREE.TextureLoader().loadAsync(url); } finally { URL.revokeObjectURL(url); }
+      texture.colorSpace = THREE.SRGBColorSpace;
+      texture.flipY = false;
+      texture.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
+      textures.set(group.id, texture);
+    }
+    gltf.scene.traverse(object => {
+      if (!object.isMesh) return;
+      let id;
+      for (let node = object; node; node = node.parent) if (node.userData.bake_group) { id = node.userData.bake_group; break; }
+      if (!textures.has(id) || !object.geometry.attributes.uv) throw new Error('Pilot mesh has no atlas mapping');
+      object.material.dispose();
+      object.material = new THREE.MeshBasicMaterial({ name: `Cycles baked diffuse | ${id}`, map: textures.get(id), toneMapped: false, fog: false });
+    });
+    const batch = batchStaticScene(gltf.scene);
+    batch.root.name = 'cycles_bake_pilot_identity_root';
+    batch.root.traverse(object => { if (object.isMesh) { object.castShadow = true; object.receiveShadow = false; } });
+    return { root: batch.root, stats: batch.sourceStats, dispose() {
+      batch.root.traverse(o => { o.geometry?.dispose(); o.material?.dispose(); });
+      textures.forEach(t => t.dispose());
+    } };
+  } catch (error) { textures.forEach(t => t.dispose()); throw error; }
+}

package/dist/stage-public/baked/bakedScene.js

@@ -0,0 +1,129 @@
+import * as THREE from 'three';
+import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { batchStaticScene } from './sceneAppearance.js';
+
+export function exrTexture(bytes, atlas = false) {
+  const d = new EXRLoader().parse(bytes);
+  const t = new THREE.DataTexture(d.data,d.width,d.height,d.format,d.type);
+  t.colorSpace = THREE.LinearSRGBColorSpace;
+  t.minFilter = THREE.LinearMipmapLinearFilter; t.magFilter = THREE.LinearFilter;
+  t.generateMipmaps = true;
+  // EXRLoader returns bottom-first rows; glTF reverses Blender's original UV V.
+  if (atlas) { t.repeat.y = -1; t.offset.y = 1; }
+  t.needsUpdate = true;
+  return t;
+}
+
+export async function loadBakedScene(manifest, readVerified, renderer) {
+  if (manifest.schema !== 'evomeme.cycles_baked_scene.v1' || manifest.display.texture_color_space !== 'Linear Rec.709') throw new Error('Unsupported linear scene bake');
+  const ownedTextures = [], ownedMaterials = new Set();
+  let root;
+  try {
+    const gltf = await new GLTFLoader().parseAsync(await readVerified(manifest.model_file),'');
+    const groupMaterials = new Map();
+    for (const group of manifest.groups) {
+      let map = null;
+      if (group.encoding === 'linear_exr') {
+        map = exrTexture(await readVerified(group.linear_master),true);
+        map.anisotropy = Math.min(8,renderer.capabilities.getMaxAnisotropy());
+        ownedTextures.push(map);
+      } else if (!group.encoding.startsWith('linear_vertex_color')) throw new Error('Unsupported surface encoding');
+      const material = new THREE.MeshBasicMaterial({name:`Cycles scene | ${group.id}`,map,vertexColors:group.encoding.startsWith('linear_vertex_color'),toneMapped:false,fog:false,side:THREE.DoubleSide});
+      if(group.encoding==='linear_vertex_color_two_sided'){
+        material.onBeforeCompile=shader=>{
+          shader.vertexShader='attribute vec3 _backlight;varying vec3 vBackLight;\n'+shader.vertexShader;
+          shader.vertexShader=shader.vertexShader.replace('#include <begin_vertex>','#include <begin_vertex>\nvBackLight=_backlight;');
+          shader.fragmentShader='varying vec3 vBackLight;\n'+shader.fragmentShader;
+          shader.fragmentShader=shader.fragmentShader.replace('#include <color_fragment>','#include <color_fragment>\nif(!gl_FrontFacing) diffuseColor.rgb=vBackLight;');
+        };
+        material.customProgramCacheKey=()=> 'baked-grass-two-sided-v1';
+      }
+      ownedMaterials.add(material); groupMaterials.set(group.id,material);
+    }
+    gltf.scene.traverse(o => {
+      if (!o.isMesh) return;
+      let id;
+      for (let p=o;p;p=p.parent) if (p.userData.bake_group) {id=p.userData.bake_group;break;}
+      const m=groupMaterials.get(id);
+      if (!m || (m.map && !o.geometry.attributes.uv) || (m.vertexColors && !o.geometry.attributes.color)) throw new Error(`Missing baked channel: ${id}`);
+      o.material.dispose(); o.material=m;
+    });
+    const batch=batchStaticScene(gltf.scene); root=batch.root;
+    root.name='full_baked_scene_identity_root';
+    root.traverse(o=>{o.castShadow=false;o.receiveShadow=false;});
+    const sky=exrTexture(await readVerified(manifest.atmosphere.sky_file)); ownedTextures.push(sky);
+    const lutUrl=URL.createObjectURL(new Blob([await readVerified(manifest.atmosphere.display_lut.file)],{type:'image/png'}));
+    let lut;
+    try {lut=await new THREE.TextureLoader().loadAsync(lutUrl);} finally {URL.revokeObjectURL(lutUrl);}
+    lut.colorSpace=THREE.NoColorSpace;lut.flipY=true;lut.generateMipmaps=false;
+    lut.minFilter=THREE.LinearFilter;lut.magFilter=THREE.LinearFilter;ownedTextures.push(lut);
+    const skyMaterial=new THREE.ShaderMaterial({side:THREE.BackSide,depthWrite:false,toneMapped:false,
+      uniforms:{radiance:{value:sky}},
+      vertexShader:'varying vec3 direction;void main(){direction=position;gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.);}',
+      fragmentShader:'varying vec3 direction;uniform sampler2D radiance;void main(){vec3 d=normalize(direction);vec2 uv=vec2(atan(d.x,-d.z)/6.28318530718+.5,asin(clamp(d.y,-1.,1.))/3.14159265359+.5);gl_FragColor=vec4(texture2D(radiance,uv).rgb,1.);}'
+    });
+    const skyMesh=new THREE.Mesh(new THREE.SphereGeometry(340,40,24),skyMaterial);
+    skyMesh.frustumCulled=false;skyMesh.renderOrder=-100;skyMesh.name='Cycles authored radiance sky';
+    return {root,sky:skyMesh,lut,stats:batch.sourceStats,update(camera){skyMesh.position.copy(camera.position);},dispose(){
+      root.traverse(o=>o.geometry?.dispose());skyMesh.geometry.dispose();skyMaterial.dispose();
+      ownedMaterials.forEach(m=>m.dispose());ownedTextures.forEach(t=>t.dispose());
+    }};
+  } catch(error) {root?.traverse(o=>o.geometry?.dispose());ownedMaterials.forEach(m=>m.dispose());ownedTextures.forEach(t=>t.dispose());throw error;}
+}
+
+/** Single scene-linear HDR pass, bounded depth fog, then the source Blender display LUT. */
+export function createBakedPipeline(renderer, baked, manifest) {
+  const target=new THREE.WebGLRenderTarget(1,1,{type:THREE.HalfFloatType,format:THREE.RGBAFormat,samples:4});
+  target.depthTexture=new THREE.DepthTexture(1,1,THREE.UnsignedIntType);
+  const postScene=new THREE.Scene();
+  const postCamera=new THREE.OrthographicCamera(-1,1,1,-1,0,1);
+  const a=manifest.atmosphere;
+  const mist=a.local_mist||[];
+  const uniforms={source:{value:target.texture},depth:{value:target.depthTexture},lut:{value:baked.lut},
+    invProjection:{value:new THREE.Matrix4()},cameraWorld:{value:new THREE.Matrix4()},cameraPositionWorld:{value:new THREE.Vector3()},
+    fogMin:{value:new THREE.Vector3().fromArray(a.fog.bounds_min)},fogMax:{value:new THREE.Vector3().fromArray(a.fog.bounds_max)},
+    fogDensity:{value:a.fog.density},fogLight:{value:new THREE.Color().fromArray(a.fog.inscatter_linear)},
+    lutSize:{value:a.display_lut.size},lutMax:{value:a.display_lut.domain_max},saturation:{value:a.compositor.saturation},
+    mistTransform:{value:mist.map(m=>new THREE.Matrix4().fromArray(m.world_to_unit))},mistDensity:{value:mist.map(m=>m.mean_density)},
+    mistLight:{value:mist.map(m=>new THREE.Vector3(...m.color_linear.map((c,i)=>c/a.fog.color_linear[i]*a.fog.inscatter_linear[i])))},
+    texel:{value:new THREE.Vector2()},glowThreshold:{value:a.compositor.glow_threshold},glowStrength:{value:a.compositor.glow_strength},displayCheck:{value:false},surfaceOnly:{value:false}};
+  const material=new THREE.ShaderMaterial({depthTest:false,depthWrite:false,toneMapped:false,uniforms,
+    vertexShader:'varying vec2 vUv;void main(){vUv=uv;gl_Position=vec4(position.xy,0.,1.);}',
+    fragmentShader:`varying vec2 vUv;uniform sampler2D source,depth,lut;uniform mat4 invProjection,cameraWorld;uniform vec3 cameraPositionWorld,fogMin,fogMax,fogLight;
+      uniform mat4 mistTransform[${Math.max(1,mist.length)}];uniform float mistDensity[${Math.max(1,mist.length)}];uniform vec3 mistLight[${Math.max(1,mist.length)}];
+      uniform float fogDensity,lutSize,lutMax,saturation,glowThreshold,glowStrength;uniform vec2 texel;uniform bool displayCheck,surfaceOnly;
+      vec3 sourceView(vec3 c){vec3 q=sqrt(clamp(c/lutMax,0.,1.))*(lutSize-1.);float b=floor(q.b);float next=min(b+1.,lutSize-1.);
+        vec2 uv0=vec2((q.r+b*lutSize+.5)/(lutSize*lutSize),(q.g+.5)/lutSize);
+        vec2 uv1=vec2((q.r+next*lutSize+.5)/(lutSize*lutSize),(q.g+.5)/lutSize);
+        return mix(texture2D(lut,uv0).rgb,texture2D(lut,uv1).rgb,fract(q.b));}
+      vec3 saturateHSV(vec3 c,float s){float hi=max(c.r,max(c.g,c.b));return max(vec3(0.),vec3(hi)+(c-vec3(hi))*s);}
+      void main(){vec3 c=texture2D(source,vUv).rgb;float z=texture2D(depth,vUv).r;
+        if(!surfaceOnly && z<.999999){vec4 v=invProjection*vec4(vUv*2.-1.,z*2.-1.,1.);v/=v.w;vec3 p=(cameraWorld*v).xyz;
+          vec3 delta=p-cameraPositionWorld;float distance=length(delta);vec3 d=delta/max(distance,.00001);
+          vec3 safeD=mix(vec3(-1.),vec3(1.),step(vec3(0.),d))*max(abs(d),vec3(.00001));vec3 t0=(fogMin-cameraPositionWorld)/safeD;vec3 t1=(fogMax-cameraPositionWorld)/safeD;
+          vec3 lo=min(t0,t1),hi=max(t0,t1);float enter=max(0.,max(lo.x,max(lo.y,lo.z)));float leave=min(distance,min(hi.x,min(hi.y,hi.z)));
+          float travel=max(0.,leave-enter);float T=exp(-fogDensity*travel);c=c*T+fogLight*(1.-T);
+          for(int i=0;i<${mist.length};i++){
+            vec3 origin=(mistTransform[i]*vec4(cameraPositionWorld,1.)).xyz;vec3 ray=(mistTransform[i]*vec4(d,0.)).xyz;
+            float A=dot(ray,ray),B=dot(origin,ray),C=dot(origin,origin)-1.;float det=B*B-A*C;
+            if(det>0.){float root=sqrt(det);float entry=max(0.,(-B-root)/A);float exit=min(distance,(-B+root)/A);
+              float span=max(0.,exit-entry);float localT=exp(-mistDensity[i]*span);c=c*localT+mistLight[i]*(1.-localT);}}
+        }
+        if(!surfaceOnly){vec3 glow=vec3(0.);for(int x=-2;x<=2;x++){for(int y=-2;y<=2;y++){
+          vec3 s=texture2D(source,vUv+vec2(float(x),float(y))*texel*3.).rgb;glow+=max(s-vec3(glowThreshold),vec3(0.));}}
+          c+=glow*glowStrength/25.;c=saturateHSV(c,saturation);}
+        if(displayCheck){int i=int(floor(vUv.x*8.));if(i==0)c=vec3(0.);else if(i==1)c=vec3(.002,.004,.008);else if(i==2)c=vec3(.02,.05,.1);else if(i==3)c=vec3(.1,.2,.3);else if(i==4)c=vec3(.5);else if(i==5)c=vec3(1.);else if(i==6)c=vec3(2.,1.,.5);else c=vec3(4.,8.,16.);}
+        gl_FragColor=vec4(sourceView(c),1.);}`});
+  const quad=new THREE.Mesh(new THREE.PlaneGeometry(2,2),material);postScene.add(quad);
+  const size=new THREE.Vector2();
+  return {render(scene,camera,{displayCheck=false,surfaceOnly=false}={}){
+    renderer.getDrawingBufferSize(size);
+    if(target.width!==size.x||target.height!==size.y)target.setSize(size.x,size.y);
+    uniforms.invProjection.value.copy(camera.projectionMatrixInverse);uniforms.cameraWorld.value.copy(camera.matrixWorld);
+    uniforms.cameraPositionWorld.value.copy(camera.position);uniforms.texel.value.set(1/size.x,1/size.y);uniforms.displayCheck.value=displayCheck;uniforms.surfaceOnly.value=surfaceOnly;
+    const autoReset=renderer.info.autoReset;renderer.info.autoReset=false;renderer.info.reset();
+    try {renderer.setRenderTarget(target);renderer.render(scene,camera);renderer.setRenderTarget(null);renderer.render(postScene,postCamera);}
+    finally {renderer.setRenderTarget(null);renderer.info.autoReset=autoReset;}
+  },dispose(){target.dispose();quad.geometry.dispose();material.dispose();}};
+}

package/dist/stage-public/baked/sceneAppearance.js

@@ -0,0 +1,225 @@
+import * as THREE from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+import { blenderLightDirection } from './sceneCamera.js';
+
+const noiseGLSL = `
+float hash31(vec3 p){ p=fract(p*0.1031); p+=dot(p,p.yzx+33.33); return fract((p.x+p.y)*p.z); }
+float noise3(vec3 x){ vec3 i=floor(x), f=fract(x); f=f*f*(3.0-2.0*f);
+  return mix(mix(mix(hash31(i),hash31(i+vec3(1,0,0)),f.x),mix(hash31(i+vec3(0,1,0)),hash31(i+vec3(1,1,0)),f.x),f.y),
+  mix(mix(hash31(i+vec3(0,0,1)),hash31(i+vec3(1,0,1)),f.x),mix(hash31(i+vec3(0,1,1)),hash31(i+vec3(1,1,1)),f.x),f.y),f.z); }
+float fbm(vec3 p){ return noise3(p)*0.53+noise3(p*2.03+17.1)*0.27+noise3(p*4.11+5.3)*0.13+noise3(p*8.21)*0.07; }
+`;
+
+function randomSequence(seed) {
+  return () => { seed |= 0; seed = seed + 0x6D2B79F5 | 0; let t = Math.imul(seed ^ seed >>> 15, 1 | seed); t ^= t + Math.imul(t ^ t >>> 7, 61 | t); return ((t ^ t >>> 14) >>> 0) / 4294967296; };
+}
+
+/** Static batching transforms cloned vertices, never the canonical root or source file. */
+export function batchStaticScene(source, { splitSourceNames = [], splitSceneNames = [] } = {}) {
+  source.updateMatrixWorld(true);
+  const selected = new Set(splitSourceNames);
+  const sceneSelected = new Set(splitSceneNames);
+  const groups = new Map();
+  let meshes = 0, triangles = 0;
+  source.traverse(object => {
+    if (!object.isMesh) return;
+    if (object.isSkinnedMesh || Array.isArray(object.material)) throw new Error('Scene batcher expects static single-material GLB meshes');
+    meshes++;
+    triangles += (object.geometry.index?.count || object.geometry.attributes.position.count) / 3;
+    const geometry = object.geometry.index ? object.geometry.toNonIndexed() : object.geometry.clone();
+    geometry.applyMatrix4(object.matrixWorld);
+    // UV channels and tangents are part of the render contract, including baked atlases.
+    for (const attribute of Object.keys(geometry.attributes)) if (!['position', 'normal', 'color', 'uv', 'uv1', 'uv2', 'uv3', 'tangent', '_backlight'].includes(attribute)) geometry.deleteAttribute(attribute);
+    let pilotSource = false, bakedSceneSource = false;
+    for (let parent = object; parent; parent = parent.parent) {
+      if (selected.has(parent.userData.canonicalSourceName)) pilotSource = true;
+      if (sceneSelected.has(parent.userData.canonicalSourceName)) bakedSceneSource = true;
+    }
+    const key = object.material.uuid + Object.keys(geometry.attributes).sort().join(',') + pilotSource + bakedSceneSource;
+    if (!groups.has(key)) groups.set(key, { material: object.material, geometries: [], names: [], pilotSource, bakedSceneSource });
+    groups.get(key).geometries.push(geometry);
+    groups.get(key).names.push(object.name);
+  });
+  const root = new THREE.Group();
+  root.name = 'canonical_identity_root';
+  for (const { material, geometries, names, pilotSource, bakedSceneSource } of groups.values()) {
+    const geometry = mergeGeometries(geometries, false);
+    if (!geometry) throw new Error(`Cannot batch ${material.name}`);
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.name = material.name;
+    mesh.userData.sourceNodes = names;
+    mesh.userData.bakePilotSource = pilotSource;
+    mesh.userData.bakedSceneSource = bakedSceneSource;
+    mesh.receiveShadow = true;
+    // Low-poly distant cliffs receive architectural shadows; disabling their
+    // huge self-caster avoids shadow-map acne without changing their geometry.
+    mesh.castShadow = !/Meadow|Airborne|Atmospheric far|Distant summit|Distant blue schist/i.test(material.name);
+    root.add(mesh);
+    geometries.forEach(g => g.dispose());
+  }
+  source.traverse(o => o.geometry?.dispose());
+  return { root, sourceStats: { meshes, triangles, batches: groups.size } };
+}
+
+export function createAppearance(scene, root, renderer, contract, profile) {
+  if (profile.schema !== 'evomeme.three_scene_profile.v1' || profile.asset_id !== contract.asset_id) throw new Error('Unsupported or mismatched Three.js appearance profile');
+  const time = { value: 0 };
+  const p = profile;
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.toneMapping = THREE.AgXToneMapping;
+  renderer.toneMappingExposure = p.render.exposure;
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  renderer.shadowMap.autoUpdate = false;
+  renderer.shadowMap.needsUpdate = true;
+  scene.fog = new THREE.Fog(p.atmosphere.fog_color, p.atmosphere.fog_near, p.atmosphere.fog_far);
+  const atmosphere = new THREE.Group();
+  atmosphere.name = 'contract_runtime_atmosphere';
+  scene.add(atmosphere);
+
+  const sunEntry = contract.blender_lights.find(l => l.type === 'SUN');
+  if (!sunEntry) throw new Error('Contract has no authored SUN');
+  const sun = new THREE.DirectionalLight(new THREE.Color().fromArray(sunEntry.color_linear), p.lighting.sun_intensity);
+  const sunDirection = blenderLightDirection(sunEntry.rotation_xyz_rad);
+  sun.target.position.fromArray(p.lighting.sun_target);
+  sun.position.copy(sun.target.position).addScaledVector(sunDirection, -130);
+  sun.castShadow = true;
+  const extent = p.lighting.shadow_extent;
+  Object.assign(sun.shadow.camera, { left: -extent, right: extent, top: extent, bottom: -extent, near: 1, far: 270 });
+  sun.shadow.mapSize.setScalar(p.render.shadow_map_size);
+  sun.shadow.normalBias = .10;
+  sun.shadow.bias = -.00012;
+  sun.shadow.camera.updateProjectionMatrix();
+  atmosphere.add(sun, sun.target);
+  atmosphere.add(new THREE.HemisphereLight(p.lighting.sky_color, p.lighting.ground_color, p.lighting.hemisphere_intensity));
+  const fill = new THREE.DirectionalLight(p.lighting.fill_color, p.lighting.fill_intensity);
+  fill.position.fromArray(p.lighting.fill_position);
+  fill.target.position.set(0, 4, -12);
+  atmosphere.add(fill, fill.target);
+
+  const skyMaterial = new THREE.ShaderMaterial({
+    side: THREE.BackSide, depthWrite: false, fog: false,
+    uniforms: {
+      uTime: time,
+      uLow: { value: new THREE.Color().fromArray(p.atmosphere.sky_low_linear) },
+      uHigh: { value: new THREE.Color().fromArray(p.atmosphere.sky_high_linear) },
+      uShadow: { value: new THREE.Color().fromArray(p.atmosphere.cloud_shadow_linear) },
+      uLight: { value: new THREE.Color().fromArray(p.atmosphere.cloud_light_linear) },
+      uScale: { value: p.atmosphere.cloud_scale }, uSpeed: { value: p.atmosphere.cloud_speed }
+    },
+    vertexShader: `varying vec3 vDirection; void main(){ vDirection=position; gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0); }`,
+    fragmentShader: `varying vec3 vDirection; uniform float uTime,uScale,uSpeed; uniform vec3 uLow,uHigh,uShadow,uLight;
+      ${noiseGLSL}
+      void main(){
+        vec3 d=normalize(vDirection); vec3 q=d*vec3(1.0,1.8,1.0)*uScale+vec3(uTime*uSpeed,0.0,1.7);
+        float n=fbm(q+fbm(q*0.6)*1.8);
+        float cloud=smoothstep(0.38,0.70,n);
+        vec3 sky=mix(uLow,uHigh,smoothstep(0.0,0.8,d.y));
+        vec3 bank=mix(uShadow,uLight,smoothstep(0.40,0.73,n));
+        // A soft cloud tower behind the western gate, in world direction space.
+        float tower=exp(-pow((d.x+0.22)/0.09,2.0)-pow((d.y-0.26)/0.27,2.0));
+        tower*=smoothstep(0.3,0.64,fbm(q*1.4+2.0));
+        sky=mix(sky,bank,cloud*.92); sky=mix(sky,uLight,tower*.62);
+        gl_FragColor=vec4(sky,1.0);
+        #include <tonemapping_fragment>
+        #include <colorspace_fragment>
+      }`
+  });
+  const sky = new THREE.Mesh(new THREE.SphereGeometry(340, 32, 20), skyMaterial);
+  sky.frustumCulled = false;
+  sky.renderOrder = -100;
+  atmosphere.add(sky);
+
+  const materialSet = new Set();
+  root.traverse(o => { if (o.isMesh) materialSet.add(o.material); });
+  for (const material of materialSet) {
+    const stone = /Limestone|limestone|slate|schist|cliffs|stone joints/.test(material.name);
+    const meadow = /Meadow|soil/.test(material.name);
+    const cliff = /schist|cliffs/.test(material.name);
+    if (cliff) material.color.multiplyScalar(p.materials.cliff_value);
+    material.roughness = .91;
+    if (material.name.includes('Airborne')) { material.emissiveIntensity = .6; continue; }
+    material.onBeforeCompile = shader => {
+      Object.assign(shader.uniforms, { uTime: time, uHaze: { value: new THREE.Color(p.atmosphere.fog_color) } });
+      shader.vertexShader = 'varying vec3 vSceneWorld;\n' + shader.vertexShader;
+      shader.vertexShader = shader.vertexShader.replace('#include <begin_vertex>', '#include <begin_vertex>\nvSceneWorld=(modelMatrix*vec4(position,1.0)).xyz;');
+      shader.fragmentShader = `varying vec3 vSceneWorld; uniform float uTime; uniform vec3 uHaze;\n${noiseGLSL}\n` + shader.fragmentShader;
+      shader.fragmentShader = shader.fragmentShader.replace('#include <color_fragment>', `#include <color_fragment>
+        float surfaceNoise=fbm(vSceneWorld*${Number(p.materials.stone_scale).toFixed(3)});
+        diffuseColor.rgb*=1.0+(surfaceNoise-.5)*${stone ? p.materials.stone_variation * 2 : p.materials.grass_variation};
+        ${stone ? 'float grain=noise3(vSceneWorld*25.0); diffuseColor.rgb*=.95+grain*.1;' : ''}
+        ${meadow ? `float cloudMask=exp(-pow((vSceneWorld.x+23.0)/18.0,2.0)-pow((vSceneWorld.z-4.0)/27.0,2.0)); diffuseColor.rgb*=1.0-cloudMask*${p.materials.cloud_shadow_strength};` : ''}
+      `);
+      shader.fragmentShader = shader.fragmentShader.replace('#include <opaque_fragment>', `
+        float heightHaze=exp(-max(vSceneWorld.y,0.0)*${p.atmosphere.height_haze_falloff})*smoothstep(40.0,135.0,length(vViewPosition))*${p.atmosphere.height_haze_strength};
+        outgoingLight=mix(outgoingLight,uHaze,heightHaze);
+        #include <opaque_fragment>`);
+      shader.fragmentShader = shader.fragmentShader.replace('#include <tonemapping_fragment>', `#include <tonemapping_fragment>
+        float luminance=dot(gl_FragColor.rgb,vec3(.2126,.7152,.0722));
+        gl_FragColor.rgb=max(vec3(0.0),mix(vec3(luminance),gl_FragColor.rgb,${p.render.saturation}));
+      `);
+    };
+    material.customProgramCacheKey = () => `sanctuary-v2-${stone}-${meadow}`;
+    material.needsUpdate = true;
+  }
+
+  const effects = new THREE.Group();
+  effects.name = 'light_threads_and_wind';
+  atmosphere.add(effects);
+  const threadMaterial = new THREE.MeshBasicMaterial({ color: p.effects.thread_color, transparent: true, opacity: p.effects.thread_opacity, depthWrite: false, toneMapped: false });
+  const groundRay = new THREE.Raycaster();
+  const meadowMesh = root.children.find(o => o.name.includes('Meadow ·'));
+  root.updateMatrixWorld(true);
+  for (const t of p.effects.light_threads) {
+    const base = new THREE.Vector3().fromArray(t.base);
+    if (meadowMesh) {
+      groundRay.set(new THREE.Vector3(base.x, 70, base.z), new THREE.Vector3(0, -1, 0));
+      const hit = groundRay.intersectObject(meadowMesh)[0];
+      if (hit) base.y = hit.point.y + .3;
+    }
+    const curve = new THREE.CatmullRomCurve3([base, base.clone().add(new THREE.Vector3(-.03, t.height * .53, 0)), base.clone().add(new THREE.Vector3(.1, t.height, 0))]);
+    effects.add(new THREE.Mesh(new THREE.TubeGeometry(curve, 12, t.radius, 4, false), threadMaterial));
+  }
+  const windMaterial = new THREE.MeshBasicMaterial({ color: '#d2e7d6', transparent: true, opacity: p.effects.wind_opacity, depthWrite: false, toneMapped: false });
+  for (const points of p.effects.wind_paths) {
+    const curve = new THREE.CatmullRomCurve3(points.map(p => new THREE.Vector3().fromArray(p)));
+    effects.add(new THREE.Mesh(new THREE.TubeGeometry(curve, 70, .018, 3, false), windMaterial));
+  }
+
+  const random = randomSequence(p.seed);
+  const count = p.effects.mote_count;
+  const positions = new Float32Array(count * 3);
+  for (let i = 0; i < count; i++) positions.set([(random() - .5) * 80, 3 + random() * 27, 15 - random() * 90], i * 3);
+  const moteGeometry = new THREE.BufferGeometry();
+  moteGeometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  const moteMaterial = new THREE.ShaderMaterial({
+    transparent: true, depthWrite: false,
+    uniforms: { uTime: time, uDpr: { value: renderer.getPixelRatio() } },
+    vertexShader: `uniform float uTime,uDpr; varying float vOpacity; void main(){ vec3 p=position; p.x+=sin(uTime*.16+position.z)*.6; p.y+=sin(uTime*.31+position.x)*.18; vec4 mv=modelViewMatrix*vec4(p,1.0); gl_Position=projectionMatrix*mv; gl_PointSize=clamp(100.0/max(6.0,-mv.z),1.0,3.0)*uDpr; vOpacity=.3+.25*sin(position.x+uTime*.8); }`,
+    fragmentShader: `varying float vOpacity; void main(){ vec2 uv=gl_PointCoord-.5; float a=1.0-smoothstep(.2,.5,length(uv*vec2(.8,1.5))); gl_FragColor=vec4(.86,.94,.85,a*vOpacity); }`
+  });
+  effects.add(new THREE.Points(moteGeometry, moteMaterial));
+  return {
+    sunDirection: sunDirection.toArray(),
+    focusCharacterShadow(position, localExtent = 4) {
+      // A tight source-sun shadow map resolves the character on the static baked plaza.
+      const extent = position ? localExtent : p.lighting.shadow_extent;
+      if (position) sun.target.position.copy(position);
+      else sun.target.position.fromArray(p.lighting.sun_target);
+      sun.position.copy(sun.target.position).addScaledVector(sunDirection, -130);
+      Object.assign(sun.shadow.camera,{left:-extent,right:extent,top:extent,bottom:-extent});
+      sun.shadow.normalBias = position ? .008 : .10;
+      sun.shadow.camera.updateProjectionMatrix();
+      renderer.shadowMap.needsUpdate = true;
+    },
+    setIsolated(isolated) { sky.visible = !isolated; effects.visible = !isolated; },
+    setAuthoredSky(enabled) { sky.visible = !enabled; },
+    update(seconds, camera) { time.value = seconds; sky.position.copy(camera.position); threadMaterial.opacity = p.effects.thread_opacity * (.95 + .05 * Math.sin(seconds * .6)); moteMaterial.uniforms.uDpr.value = renderer.getPixelRatio(); },
+    dispose() {
+      scene.remove(atmosphere);
+      const geometries = new Set(), materials = new Set();
+      atmosphere.traverse(o => { if (o.geometry) geometries.add(o.geometry); if (o.material) materials.add(o.material); });
+      geometries.forEach(g => g.dispose()); materials.forEach(m => m.dispose()); sun.shadow.dispose();
+    }
+  };
+}

package/dist/stage-public/baked/sceneCamera.js

@@ -0,0 +1,45 @@
+import * as THREE from 'three';
+
+export function applySceneCamera(camera, controls, definition) {
+  if (!definition) throw new Error('Missing contract camera');
+  camera.position.fromArray(definition.position);
+  camera.quaternion.fromArray(definition.quaternion_xyzw).normalize();
+  camera.up.fromArray(definition.up || [0, 1, 0]);
+  camera.fov = definition.vertical_fov_rad * 180 / Math.PI;
+  camera.aspect = definition.aspect_ratio;
+  camera.near = definition.near;
+  camera.far = definition.far;
+  camera.updateProjectionMatrix();
+  camera.updateMatrixWorld(true);
+  if (controls) controls.target.fromArray(definition.look_at);
+}
+
+export function fitFrame(width, height, aspect) {
+  const w = Math.min(width, height * aspect);
+  return { width: Math.max(1, w), height: Math.max(1, w / aspect) };
+}
+
+export function inspectScene(root, camera, contract, cameraId) {
+  root.updateMatrixWorld(true);
+  const near = (a, b, tolerance = 0.0001) => a.length === b.length && a.every((v, i) => Number.isFinite(v) && Math.abs(v - b[i]) < tolerance);
+  const box = new THREE.Box3().setFromObject(root, true);
+  const c = contract.cameras.find(c => c.id === cameraId);
+  const identity = new THREE.Matrix4();
+  const results = [
+    { name: '根矩阵保持原点 / 米制 / 原轴向', passed: near(root.matrixWorld.elements, identity.elements) },
+    { name: '实际 GLB 包围盒符合源契约', passed: near(box.min.toArray(), contract.coordinates.bounds_gltf_metres.min, .002) && near(box.max.toArray(), contract.coordinates.bounds_gltf_metres.max, .002) }
+  ];
+  if (c) {
+    const q = new THREE.Quaternion().fromArray(c.quaternion_xyzw).normalize();
+    results.push({ name: `${c.id} 相机位置及旋转`, passed: near(camera.position.toArray(), c.position) && 1 - Math.abs(camera.quaternion.dot(q)) < 1e-7 });
+    results.push({ name: '投影 / 裁剪面 / 1.88 画幅', passed: near([camera.fov, camera.aspect, camera.near, camera.far], [c.vertical_fov_degrees, c.aspect_ratio, c.near, c.far]) });
+  }
+  return results;
+}
+
+// Blender Euler XYZ applies fixed X, then Y, then Z: Rz * Ry * Rx.
+// Three's intrinsic ZYX produces that matrix (intrinsic XYZ does not).
+export function blenderLightDirection(rotation) {
+  const d = new THREE.Vector3(0, 0, -1).applyEuler(new THREE.Euler(...rotation, 'ZYX'));
+  return new THREE.Vector3(d.x, d.z, -d.y).normalize();
+}

package/dist/stage-public/comparison-contract.js

@@ -0,0 +1,28 @@
+const close = (actual, expected, tolerance = .001) => Array.isArray(actual) && Array.isArray(expected) && actual.length === expected.length && actual.every((v, i) => Number.isFinite(v) && Number.isFinite(expected[i]) && Math.abs(v - expected[i]) <= tolerance);
+const result = (state, label, detail) => ({ state, label, detail });
+
+// Check only requirements actually declared by this asset. No inferred gameplay requirements.
+export function compareSpatial(contract, stats, recipe) {
+  const c = contract?.coordinates;
+  if (!c) return result('warn', '未声明约束', '资产契约未声明空间要求。');
+  const failures = [];
+  if (c.root_transform) {
+    if (!close(recipe.translation_metres, c.root_transform.position) || !close(recipe.scale_xyz, c.root_transform.scale)) failures.push('根位置或尺寸');
+    const q = c.root_transform.quaternion_xyzw;
+    if (!close(recipe.rotation_quaternion_xyzw, q) && !close(recipe.rotation_quaternion_xyzw, q?.map(v => -v))) failures.push('根旋转');
+  }
+  if (c.bounds_gltf_metres) for (const key of ['min', 'max']) if (!close(stats.bounds[key], c.bounds_gltf_metres[key], .01)) failures.push(`场景边界 ${key}`);
+  if (failures.length) return result('error', '存在偏差', `${failures.join('、')}与契约不符。`);
+  if (!c.root_transform && !c.bounds_gltf_metres) return result('warn', '部分已检查', '轴向元数据已检查；契约未声明根变换或边界。');
+  return result('ok', '符合声明约束', `${stats.size.map(n => n.toFixed(2)).join(' × ')} m · 保留场景原点`);
+}
+export function compareStructural(contract, stats) {
+  const contents = contract?.contents;
+  if (!contents) return result('warn', '未声明数量', `已载入 ${stats.meshes} 网格；契约未声明结构数量。`);
+  const mappings = { mesh_count: 'meshes', node_count: 'nodes', material_count: 'materials', animations: 'animations', camera_count: 'cameras', skin_count: 'skins' };
+  const declared = Object.entries(mappings).filter(([k]) => typeof contents[k] === 'number');
+  const failures = declared.filter(([k, stat]) => contents[k] !== stats[stat]).map(([k]) => k);
+  if (failures.length) return result('error', '存在偏差', `与契约不符：${failures.join('、')}`);
+  if (!declared.length) return result('warn', '未声明数量', '已载入原始层级，尚无可比对的结构数量约束。');
+  return result('ok', '符合声明数量', `${stats.nodes} 节点 · ${stats.meshes} 网格 · ${stats.materials} 材质`);
+}

package/dist/stage-public/delivery.html

@@ -0,0 +1,4 @@
+<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>已确认资产 · Three.js</title>
+<style>html,body{margin:0;background:#151d20;color:#cce2dc;font:14px system-ui;height:100%}header{height:50px;display:flex;align-items:center;justify-content:space-between;padding:0 24px;border-bottom:1px solid #344044}#view{height:calc(100% - 51px);display:grid;place-items:center}.render-frame canvas{display:block}a{color:#a5dec9}</style>
+<script type="importmap">{"imports":{"three":"./vendor/three170/build/three.module.js","three/addons/":"./vendor/three170/examples/jsm/"}}</script>
+<header><strong id="title">读取已确认资产…</strong><span id="status">校验版本与显示资源</span><a href="./HANDOFF.md">交互设计接入说明</a></header><div id="view"></div><script type="module" src="./delivery.js"></script></html>

package/dist/stage-public/delivery.js

@@ -0,0 +1,17 @@
+import { createReviewView } from './review-runtime.js';
+try {
+  const delivery = await fetch('./delivery.json').then(r => r.json());
+  const bytes = await Promise.all(Object.entries(delivery.integrity).map(async ([file, expected]) => {
+    const r = await fetch(`./${file}`); if (!r.ok) throw new Error(`Missing asset: ${file}`);
+    const data = await r.arrayBuffer();
+    const hash = [...new Uint8Array(await crypto.subtle.digest('SHA-256', data))].map(n => n.toString(16).padStart(2, '0')).join('');
+    if (hash !== expected) throw new Error(`Delivery file changed: ${file}`); return [file, ['confirmation.json', 'asset/asset.json', 'asset/scene.contract.json'].includes(file) ? data : null];
+  }));
+  const resources = Object.fromEntries(bytes), json = key => JSON.parse(new TextDecoder().decode(resources[key]));
+  const record = json('confirmation.json');
+  const view = await createReviewView({ container: document.querySelector('#view'), assetBase: new URL('./asset/', location.href), asset: json('asset/asset.json'), contract: resources['asset/scene.contract.json'] ? json('asset/scene.contract.json') : null,
+    files: record.files, presentation: delivery.presentation, profile: record.target_profile, onProgress: message => document.querySelector('#status').textContent = message });
+  document.querySelector('#title').textContent = `${delivery.asset_id} · 已确认版本`;
+  document.querySelector('#status').textContent = '同一显示实现 · 可拖动观察 · 交互尚未设计';
+  window.addEventListener('pagehide', () => view.dispose());
+} catch (error) { document.querySelector('#status').textContent = error.message; console.error(error); }