evomeme 0.1.9 → 0.1.10-beta.13

package/dist/stage-public/review-app.js

@@ -0,0 +1,289 @@
+import { createReviewView } from './review-runtime.js';
+import { compareSpatial, compareStructural } from './comparison-contract.js';
+
+const $ = id => document.getElementById(id);
+// The task chooses the scene. Never enumerate packages or substitute another asset.
+const assetId = new URLSearchParams(location.search).get('asset');
+let view, check, cameraChoices = [], aspect = 1.88, busy = false, referenceUrl, cameraEpoch = 0;
+let renderTimer, renderEpoch = 0, currentJob, interacting = false, needsRender = false;
+const apiBase = `/api/packages/${encodeURIComponent(assetId)}`;
+let targetEngine = new URLSearchParams(location.search).get('engine') === 'godot' ? 'godot' : 'three_js';
+let stageView, viewedCapture, godotUrl, hasReference = false;
+$('target-engine').value = targetEngine;
+const engineName = () => targetEngine === 'godot' ? 'Godot' : 'Three.js';
+function renderAdaptation() {
+  const report = check.adaptation?.[targetEngine], panel = $('adaptation-panel');
+  panel.hidden = !report;
+  if (!report) return;
+  const labels = {mapped:'已映射',baked:'已烘焙',approximate:'采用近似',missing:'尚未实现',unverified:'待核对'};
+  $('adaptation-summary').textContent = `${report.summary.missing || 0} 项尚未实现 · ${report.summary.approximate || 0} 项采用近似`;
+  const source = check.contract?.source_features?.rendering;
+  $('adaptation-scope').textContent = `${engineName()} · ${report.renderer}　|　Blender ${source?.engine || '源设置未记录'} · ${source?.preview_quality === 'final' ? '源采样参考图' : '快速参考图'}。自由视角使用快速原生渲染。`;
+  $('adaptation-items').replaceChildren();
+  for (const item of report.items) {
+    const row = document.createElement('div'); row.className = 'adaptation-row';
+    const title = document.createElement('div'); title.className = 'adaptation-title';
+    const name = document.createElement('strong'); name.textContent = item.label;
+    const badge = document.createElement('span'); badge.className = `adaptation-badge ${item.status}`; badge.textContent = labels[item.status];
+    title.append(name,badge);
+    const description = document.createElement('p'); description.textContent = item.detail;
+    const action = document.createElement('p'); action.className = 'adaptation-action'; action.textContent = item.action;
+    const buttons = document.createElement('div'); buttons.className = 'adaptation-buttons';
+    const inspect = document.createElement('button'); inspect.textContent = '查看相关机位';
+    inspect.onclick = () => {
+      if (busy) return;
+      const index = cameraChoices.findIndex(c => c.camera?.id === item.camera_id);
+      $('camera').value = String(Math.max(index,0));
+      setCamera(Math.max(index,0)).catch(failed);
+      document.querySelector('.viewer').scrollIntoView({behavior:'smooth',block:'start'});
+    };
+    const request = document.createElement('button'); request.textContent = '记录修复要求';
+    request.onclick = async () => {
+      if (busy || !view || !stageView) { message('当前画面就绪后可记录修复要求。'); return; }
+      request.disabled = true;
+      try {
+        await post('feedback',{revision:check.revision,presentation:view.capture().presentation,
+          object_name:(item.object_names || []).join(', '),instruction:`目标 ${engineName()}，修复「${item.label}」：${item.detail} ${item.action}`});
+        request.textContent = '已记录，回对话继续'; message('修复要求已保存在当前资产中；回到建模对话继续处理。');
+      } catch(error) { message(error.message); request.disabled = false; }
+    };
+    buttons.append(inspect,request); row.append(title,description,action,buttons); $('adaptation-items').append(row);
+  }
+  panel.open = report.summary.missing > 0;
+}
+function resetConfirmation() { stageView = null; viewedCapture = null; $('confirm-asset').disabled = true; $('confirmation-state').textContent = '当前画面待确认'; document.querySelector('.confirmation-bar').classList.remove('confirmed'); }
+async function post(endpoint, body) {
+  const response = await fetch(`${apiBase}/${endpoint}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  const result = await response.json(); if (!response.ok || !result.ok) throw new Error(result.error || 'Stage request failed.'); return result;
+}
+async function finishView() {
+  const epoch = renderEpoch, engine = targetEngine;
+  resetConfirmation();
+  const capture = view.capture(); let native;
+  if (engine === 'godot') {
+    $('godot-image').hidden = true; $('godot-pending').hidden = false; $('godot-progress').textContent = 'Godot 正在渲染当前机位…';
+    try {
+      native = await post('godot-preview', { revision: check.revision, presentation: capture.presentation });
+      if (epoch !== renderEpoch || engine !== targetEngine) return;
+      const image = await verifiedImage(native.image_url,native);
+      if (epoch !== renderEpoch) { URL.revokeObjectURL(image.url); return; }
+      if (godotUrl) URL.revokeObjectURL(godotUrl); godotUrl = image.url;
+      $('godot-image').src = image.url; $('godot-image').hidden = false; $('godot-pending').hidden = true;
+      capture.screenshot = await fetch(image.url).then(r => r.blob()).then(blob => new Promise(resolve => { const reader = new FileReader(); reader.onload = () => resolve(reader.result); reader.readAsDataURL(blob); }));
+      $('engine-render-label').textContent = `原生 ${native.native.version}`;
+      $('confirmation-note').textContent = [hasReference ? '请核对 Godot 的材质、灯光和阴影，再确认当前版本。' : '未提供 Blender 基准；只确认目标引擎效果，不代表与 Blender 画面一致。',...native.profile.warnings].join(' ');
+    } catch (error) {
+      if (epoch === renderEpoch) { $('godot-progress').textContent = error.message; message(error.message); }
+      throw error;
+    }
+  }
+  if (epoch !== renderEpoch || engine !== targetEngine) return;
+  const receipt = await post('stage-view', { revision: check.revision, presentation: capture.presentation, engine, godot_preview_id: native?.id });
+  if (epoch !== renderEpoch || engine !== targetEngine) return;
+  stageView = receipt; viewedCapture = capture;
+  if (!hasReference) checkState('appearance', {state:'warn',label:'目标引擎已载入',detail:'未提供 Blender 基准；请查看当前材质与灯光效果。'});
+  $('confirmation-state').textContent = `${engineName()} 当前版本待用户确认`;
+  $('confirm-asset').disabled = false;
+}
+const message = text => { $('status').textContent = text; $('loading-text').textContent = text; };
+function checkState(kind, value) { $(`${kind}-state`).className = `check-state ${value.state}`; $(`${kind}-state`).textContent = value.label; $(`${kind}-detail`).textContent = value.detail; }
+function split(value) {
+  const n = Math.max(0, Math.min(100, value));
+  $('comparison').style.setProperty('--split', `${n}%`);
+  $('divider').setAttribute('aria-valuenow', String(Math.round(n)));
+  $('divider').setAttribute('aria-valuetext', `左侧 Blender ${Math.round(n)}%，右侧 ${engineName()} ${Math.round(100 - n)}%`);
+  document.querySelector('.source-label').hidden = n === 0;
+  document.querySelector('.engine-label').hidden = n === 100;
+}
+function fit() {
+  const w = Math.min($('stage').clientWidth, $('stage').clientHeight * aspect);
+  $('comparison').style.width = `${w}px`; $('comparison').style.height = `${w / aspect}px`;
+}
+const resizeObserver = new ResizeObserver(fit); resizeObserver.observe($('stage'));
+function drag(event) { const r = $('comparison').getBoundingClientRect(); split((event.clientX - r.left) / r.width * 100); }
+$('divider').addEventListener('pointerdown', event => { event.stopPropagation(); if (event.button !== 0 || busy) return; event.preventDefault(); $('divider').focus({ preventScroll: true }); $('divider').setPointerCapture(event.pointerId); drag(event); });
+$('divider').addEventListener('pointermove', event => { event.stopPropagation(); if ($('divider').hasPointerCapture(event.pointerId)) drag(event); });
+for (const type of ['pointerup', 'pointercancel']) $('divider').addEventListener(type, event => { event.stopPropagation(); if ($('divider').hasPointerCapture(event.pointerId)) $('divider').releasePointerCapture(event.pointerId); });
+$('divider').addEventListener('keydown', event => {
+  const current = Number($('divider').getAttribute('aria-valuenow'));
+  const values = { ArrowLeft: current - 2, ArrowDown: current - 2, ArrowRight: current + 2, ArrowUp: current + 2, Home: 0, End: 100 };
+  if (event.key in values) { event.preventDefault(); split(values[event.key]); }
+});
+async function verifiedImage(file, fingerprint) {
+  const response = await fetch(fingerprint ? file : `${apiBase}/files/${file}?revision=${check.revision}`);
+  if (!response.ok) throw new Error('Failed to read the Blender reference.');
+  const bytes = await response.arrayBuffer(), expected = fingerprint || check.files[file];
+  const hash = [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(n => n.toString(16).padStart(2, '0')).join('');
+  if (!expected || hash !== expected.sha256 || bytes.byteLength !== expected.bytes) throw new Error('The Blender reference changed. Reload the scene.');
+  const url = URL.createObjectURL(new Blob([bytes], { type: 'image/png' })), img = new Image(); img.src = url;
+  try { await img.decode(); } catch (error) { URL.revokeObjectURL(url); throw error; }
+  return { url, width: img.naturalWidth, height: img.naturalHeight };
+}
+function cancelJob(id) { if (id) fetch(`${apiBase}/blender-preview/${id}/cancel`, { method: 'POST', keepalive: true }).catch(() => {}); }
+function invalidatePreview() { ++renderEpoch; clearTimeout(renderTimer); cancelJob(currentJob); currentJob = null; needsRender = false; resetConfirmation(); if (targetEngine === 'godot') { $('godot-image').hidden = true; $('godot-pending').hidden = false; $('godot-progress').textContent = '当前机位待更新…'; } }
+function nativePending(text, error = false) {
+  $('blender-view').classList.add('pending'); $('blender-pending').hidden = false;
+  $('blender-pending').classList.toggle('error', error); $('blender-progress').textContent = text;
+  $('retry-preview').hidden = !error; $('view-state').textContent = error ? 'Blender 视角更新失败' : '正在同步当前视角';
+  $('blender-label').textContent = error ? '当前视角未就绪' : '正在更新机位';
+  checkState('appearance', { state: 'warn', label: '当前视角待更新', detail: 'Three.js 已更新；等待同机位 Blender 原生渲染。' });
+}
+function nativeReady(image, label) {
+  if (referenceUrl) URL.revokeObjectURL(referenceUrl);
+  referenceUrl = image.url; $('blender-image').src = image.url;
+  $('blender-view').classList.remove('pending'); $('blender-pending').hidden = true;
+  $('blender-label').textContent = label; $('view-state').textContent = '对齐后的实际效果';
+  checkState('appearance', { state: 'warn', label: '显示已应用 · 待比对', detail: view.mode === 'baked' ? '已应用源烘焙与显示配方 · 拖动对比渲染差异' : '已应用目标引擎材质 · 拖动对比渲染差异' });
+}
+function cameraChanged() {
+  if (busy || !view) return;
+  invalidatePreview(); needsRender = true; $('camera').value = 'free';
+  nativePending(interacting ? '松开后更新 Blender 视角' : '准备渲染当前视角…');
+  $('camera-note').textContent = '自由视角 · 共享相机';
+  message('Three.js 实时响应；Blender 停止操作后按同一机位重新渲染。');
+  if (!interacting) schedulePreview();
+}
+function schedulePreview() { clearTimeout(renderTimer); if (needsRender) renderTimer = setTimeout(renderPreview, 450); }
+async function renderPreview() {
+  if (!view || busy || interacting) return;
+  if (!hasReference) {
+    needsRender = false;
+    try { await finishView(); } catch (error) { message(error.message); }
+    return;
+  }
+  needsRender = false;
+  const epoch = renderEpoch, revision = check.revision, camera = view.getCamera();
+  nativePending('Blender 正在渲染当前视角…');
+  const started = performance.now();
+  try {
+    const response = await fetch(`${apiBase}/blender-preview`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ revision, camera }) });
+    let job = await response.json();
+    if (epoch !== renderEpoch) { if (job.id) cancelJob(job.id); return; }
+    if (!response.ok || !job.ok) throw new Error(job.error || 'Blender preview request failed.');
+    currentJob = job.id;
+    while (job.state === 'queued' || job.state === 'rendering') {
+      if (epoch !== renderEpoch) return;
+      const seconds = Math.round((performance.now() - started) / 1000);
+      $('blender-progress').textContent = `${job.state === 'queued' ? '等待上一帧结束' : 'Blender 正在渲染'} · ${seconds} 秒`;
+      await new Promise(resolve => setTimeout(resolve, 700));
+      if (epoch !== renderEpoch) return;
+      const result = await fetch(`${apiBase}/blender-preview/${job.id}`); job = await result.json();
+      if (!result.ok || !job.ok) throw new Error(job.error || 'Failed to read Blender render progress.');
+    }
+    if (epoch !== renderEpoch) return;
+    if (job.state !== 'ready') throw new Error(job.error || 'This view was superseded. Retry the current view.');
+    if (job.revision !== revision || JSON.stringify(job.camera) !== JSON.stringify(camera)) throw new Error('Blender 返回机位与当前视角不一致');
+    const image = await verifiedImage(job.image_url, job);
+    if (epoch !== renderEpoch) { URL.revokeObjectURL(image.url); return; }
+    if (Math.abs(image.width / image.height - aspect) > .003) { URL.revokeObjectURL(image.url); throw new Error('Blender 返回画幅与当前机位不一致'); }
+    nativeReady(image, `Blender · ${job.receipt.samples} samples 预览`);
+    await finishView();
+    $('camera-note').textContent = `自由视角 · ${image.width} × ${image.height} · ${job.receipt.seconds} 秒`;
+    message('两侧已同步到当前机位。Blender 为原生快速预览；可继续旋转、平移、缩放或拖动分隔线。');
+    currentJob = null;
+  } catch (error) {
+    if (epoch !== renderEpoch) return;
+    nativePending('当前视角未生成，可重试或切回参考机位。', true); message(error.message); currentJob = null;
+  }
+}
+$('retry-preview').addEventListener('pointerdown', e => e.stopPropagation());
+$('retry-preview').onclick = () => { invalidatePreview(); renderPreview(); };
+async function setCamera(index) {
+  const choice = cameraChoices[index], epoch = ++cameraEpoch;
+  if (!choice) return;
+  invalidatePreview(); view?.setInteractive(false);
+  busy = true; $('camera').disabled = true; $('reload').disabled = true; $('target-engine').disabled = true; $('comparison').hidden = true; $('loading').hidden = false;
+  $('loading').classList.remove('error');
+  message('对齐 Blender 与 Three.js 的机位和画幅…');
+  try {
+    if (!choice.file) {
+      view.resetCamera(); aspect = view.getCamera().aspect; fit(); split(0);
+      $('comparison').hidden = false; $('loading').hidden = true;
+      $('view-state').textContent = '目标引擎实际预览'; $('camera-note').textContent = '未提供 Blender 基准，当前只核对目标引擎效果';
+      $('confirmation-note').textContent = '未提供 Blender 基准。请查看目标引擎实际材质与灯光；此确认不代表与 Blender 画面一致。';
+      await finishView();
+      message('当前为目标引擎预览。可旋转、平移、缩放，查看后确认当前版本。');
+      return;
+    }
+    const image = await verifiedImage(choice.file);
+    if (epoch !== cameraEpoch) { URL.revokeObjectURL(image.url); return; }
+    aspect = choice.camera.aspect_ratio;
+    if (Math.abs(image.width / image.height - aspect) > .001) { URL.revokeObjectURL(image.url); throw new Error('Blender 基准画幅与契约相机不一致'); }
+    nativeReady(image, 'Blender · 原生渲染');
+    view.setCamera(choice.camera); fit(); $('comparison').hidden = false;
+    await finishView();
+    $('loading').hidden = true; $('view-state').textContent = '对齐后的实际效果';
+    $('camera-note').textContent = `${choice.label} · ${image.width} × ${image.height} 基准画幅`;
+    message('拖动画面改变共享机位；停止操作后 Blender 更新。拖动分隔线对比两侧效果。');
+  } finally { busy = false; view?.setInteractive(true); $('camera').disabled = false; $('reload').disabled = false; $('target-engine').disabled = false; }
+}
+function failed(error) {
+  resetConfirmation();
+  $('comparison').hidden = true; $('loading').hidden = false; $('loading').classList.add('error'); $('view-state').textContent = '对比未就绪';
+  for (const kind of ['spatial', 'structural']) if ($(`${kind}-state`).textContent === '检查中') checkState(kind, { state: 'warn', label: '未完成', detail: '本次导入未完成，尚不能判断契约是否满足。' });
+  checkState('appearance', { state: 'error', label: '无法对比', detail: '两侧需要同一场景、同一机位的有效结果。' });
+  message(error.message); console.error(error);
+}
+async function load() {
+  if (busy) return;
+  if (!assetId) { failed(new Error('当前任务未指定场景。请由建模任务传入 asset_id 后打开视窗。')); return; }
+  busy = true; $('reload').disabled = true; $('camera').disabled = true; $('target-engine').disabled = true; $('comparison').hidden = true; $('loading').hidden = false; $('loading').classList.remove('error');
+  $('engine-name').textContent = engineName(); $('godot-image').hidden = true; $('godot-pending').hidden = targetEngine !== 'godot';
+  document.title = `场景对齐 · Blender / ${engineName()}`;
+  document.querySelector('.viewer').setAttribute('aria-label', `当前场景的 Blender 与 ${engineName()} 对比`);
+  $('divider').setAttribute('aria-label', `Blender 与 ${engineName()} 对比滑条`);
+  $('engine-view').style.visibility = targetEngine === 'godot' ? 'hidden' : '';
+  $('engine-render-label').textContent = targetEngine === 'godot' ? '等待原生渲染' : '当前引擎渲染';
+  invalidatePreview(); ++cameraEpoch; interacting = false; $('comparison').classList.remove('orbiting');
+  $('revision').textContent = '';
+  view?.dispose(); view = null; check = null; $('title').textContent = assetId === 'windworn_sanctuary' ? '风蚀圣域' : assetId; $('asset-id').textContent = assetId;
+  for (const kind of ['spatial', 'structural', 'appearance']) checkState(kind, { state: '', label: '检查中', detail: '读取当前资产契约…' });
+  message('检查当前场景的模型、资产契约与显示依赖…');
+  try {
+    const response = await fetch(`/api/packages/${encodeURIComponent(assetId)}/review`, { method: 'POST' });
+    const result = await response.json(); if (!response.ok || !result.ok) throw new Error(result.error || 'Scene validation failed.'); check = result;
+    if (!check.technical_ok) throw new Error(`模型格式存在 ${check.report.issues.numErrors} 个错误，请在建模任务中修复后重新导入。`);
+    const contract = check.contract;
+    const reference = contract?.source_of_truth?.reference_camera || 'reference';
+    cameraChoices = (contract?.cameras || []).map(camera => ({ camera, label: camera.label || (camera.id === reference ? '参考机位' : camera.id === 'overview' ? '全景机位' : camera.id),
+      file: camera.reference_render || (camera.id === reference ? contract.source_of_truth?.reference_render || 'preview/blender_reference.png' : camera.id === 'overview' ? 'preview/blender_overview.png' : null) })).filter(c => c.file && check.files[c.file]);
+    hasReference = cameraChoices.length > 0;
+    if (!hasReference) cameraChoices = [{camera:null,label:'模型预览',file:null}];
+    $('divider').hidden = !hasReference;
+    $('blender-view').hidden = !hasReference;
+    document.querySelector('.frame-note').textContent = hasReference ? '同机位 · 同画幅' : '目标引擎预览';
+    $('camera').replaceChildren(...cameraChoices.map((choice, i) => { const o = document.createElement('option'); o.value = String(i); o.textContent = choice.label; return o; }));
+    const free = document.createElement('option'); free.value = 'free'; free.textContent = '自由视角'; free.disabled = true; $('camera').append(free);
+    aspect = cameraChoices[0].camera?.aspect_ratio || 1.6; fit();
+    $('comparison').hidden = false; $('comparison').style.visibility = 'hidden';
+    view = await createReviewView({ container: $('engine-view'), assetBase: `${apiBase}/files/`, asset: check.asset, contract, files: check.files, profile: check.profiles?.three_js,
+      interactive: false, controlElement: $('comparison'), onCameraChange: cameraChanged,
+      onCameraStart: () => { interacting = true; $('comparison').classList.add('orbiting'); clearTimeout(renderTimer); },
+      onCameraEnd: () => { interacting = false; $('comparison').classList.remove('orbiting'); schedulePreview(); }, onProgress: message });
+    const recipe = { translation_metres: view.root.position.toArray(), rotation_quaternion_xyzw: view.root.quaternion.toArray(), scale_xyz: view.root.scale.toArray() };
+    checkState('spatial', compareSpatial(contract, view.stats, recipe));
+    checkState('structural', compareStructural(contract, view.stats));
+    renderAdaptation();
+    $('revision').textContent = `资产 ${check.files['model.glb'].sha256.slice(0, 10)}${contract ? ` · 契约 r${contract.contract_revision || 1}` : ''}`;
+    $('comparison').style.visibility = ''; split(50); await setCamera(0);
+  } catch (error) { failed(error); }
+  finally { busy = false; $('reload').disabled = false; $('target-engine').disabled = false; }
+}
+$('reload').onclick = load;
+$('target-engine').onchange = () => { targetEngine = $('target-engine').value; invalidatePreview(); if (!busy) load(); };
+$('confirm-asset').onclick = async () => {
+  if (!stageView || !viewedCapture || busy || interacting) return;
+  busy = true; $('confirm-asset').disabled = true; $('reload').disabled = true; $('camera').disabled = true; $('target-engine').disabled = true; view.setInteractive(false);
+  try {
+    const result = await post('confirmation', { accepted: true, revision: check.revision, stage_view_token: stageView.token, ...viewedCapture });
+    check.revision = result.revision;
+    $('confirmation-state').textContent = `${engineName()} 当前版本已确认，可以导入`;
+    document.querySelector('.confirmation-bar').classList.add('confirmed');
+    message('确认已保存。可回到原任务继续导入；修改模型、材质、灯光或显示配置后，必须回 Stage 重新确认。');
+    stageView = null; viewedCapture = null;
+  } catch (error) { resetConfirmation(); message(error.message); }
+  finally { busy = false; $('reload').disabled = false; $('camera').disabled = false; $('target-engine').disabled = false; view.setInteractive(true); }
+};
+$('camera').onchange = () => setCamera(Number($('camera').value)).catch(failed);
+window.addEventListener('pagehide', () => { ++cameraEpoch; invalidatePreview(); resizeObserver.disconnect(); view?.dispose(); if (referenceUrl) URL.revokeObjectURL(referenceUrl); });
+load();

package/dist/stage-public/review-runtime.js

@@ -0,0 +1,63 @@
+/** Viewer UI. Scene appearance is shared with synchronized game projects. */
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { loadCanonicalScene, applySceneCamera } from './scene-runtime.js';
+
+export async function createReviewView({ container, assetBase, asset, contract = null, files, presentation, profile = null,
+  interactive = true, controlElement, onCameraChange = () => {}, onCameraStart = () => {}, onCameraEnd = () => {}, onProgress = () => {} }) {
+  const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
+  renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5));
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.toneMapping = THREE.AgXToneMapping;
+  renderer.toneMappingExposure = 1;
+  const frame = document.createElement('div');
+  frame.className = 'render-frame'; frame.append(renderer.domElement); container.replaceChildren(frame);
+  const world = new THREE.Scene(), camera = new THREE.PerspectiveCamera(40, 1.6, .01, 2000);
+  const controls = new OrbitControls(camera, controlElement || renderer.domElement);
+  controls.enableDamping = false; controls.enabled = interactive;
+  let scene, observer, disposed = false;
+  try {
+    scene = await loadCanonicalScene({ renderer, world, assetBase, asset, contract, files, presentation, profile, onProgress });
+    const { root, stats, inventory, mode } = scene;
+    const center = new THREE.Box3(new THREE.Vector3().fromArray(stats.bounds.min), new THREE.Vector3().fromArray(stats.bounds.max)).getCenter(new THREE.Vector3());
+    const radius = Math.max(...stats.size, .1);
+    controls.target.copy(center); camera.position.copy(center).add(new THREE.Vector3(.9, .55, 1.3).multiplyScalar(radius)); camera.lookAt(center);
+    camera.near = Math.max(.001, radius / 2000); camera.far = Math.max(100, radius * 20);
+    let aspect = presentation?.camera.aspect || contract?.cameras?.[0]?.aspect_ratio || 1.6;
+    function render() { if (!disposed) scene.render(camera); }
+    function setCamera(value) {
+      if (!value) return;
+      applySceneCamera(camera, value); controls.target.fromArray(value.target || value.look_at); aspect = camera.aspect; render();
+    }
+    function getCamera() { return { position: camera.position.toArray(), quaternion: camera.quaternion.toArray(), target: controls.target.toArray(), fov: camera.fov, aspect: camera.aspect, near: camera.near, far: camera.far }; }
+    function resize() {
+      const width = Math.max(1, Math.min(container.clientWidth, container.clientHeight * aspect));
+      frame.style.width = `${width}px`; frame.style.height = `${width / aspect}px`;
+      renderer.setSize(width, width / aspect, true); camera.aspect = aspect; camera.updateProjectionMatrix(); render();
+    }
+    controls.addEventListener('change', () => { render(); onCameraChange(getCamera()); });
+    controls.addEventListener('start', onCameraStart); controls.addEventListener('end', onCameraEnd);
+    observer = new ResizeObserver(resize); observer.observe(container);
+    setCamera(presentation?.camera || contract?.cameras?.find(c => c.id === 'reference') || contract?.cameras?.[0]);
+    const initialCamera = getCamera(); resize(); onProgress('编译显示材质…'); await renderer.compileAsync(world, camera); render();
+    return {
+      root, world, camera, renderer, inventory, mode, stats, setCamera, getCamera, render,
+      setInteractive: enabled => { controls.enabled = enabled; }, resetCamera: () => setCamera(initialCamera),
+      diagnostic(kind) { scene.diagnostic(kind); render(); },
+      focus(index) {
+        const object = inventory[index]?.object; if (!object) return;
+        const box = new THREE.Box3().setFromObject(object, true), c = box.getCenter(new THREE.Vector3()), r = Math.max(box.getSize(new THREE.Vector3()).length(), 1);
+        controls.target.copy(c); camera.position.copy(c).add(new THREE.Vector3(1, .7, 1).multiplyScalar(r)); camera.lookAt(c); render();
+      },
+      capture() {
+        if (scene.diagnosticActive) throw new Error('Switch back to the material view before confirming.'); render();
+        return { screenshot: renderer.domElement.toDataURL('image/png'), presentation: { renderer: 'evomeme.review.v1', three_revision: THREE.REVISION, mode, camera: getCamera(),
+          recipe: { translation_metres: root.position.toArray(), rotation_quaternion_xyzw: root.quaternion.toArray(), scale_xyz: root.scale.toArray(), algorithm_version: 'evomeme.review.v1' } } };
+      }, dispose
+    };
+  } catch (error) { dispose(); throw error; }
+  function dispose() {
+    if (disposed) return; disposed = true;
+    observer?.disconnect(); controls.dispose(); scene?.dispose(); renderer.dispose(); frame.remove();
+  }
+}

package/dist/stage-public/review.css

@@ -0,0 +1,24 @@
+:root{color-scheme:dark;--bg:#131819;--panel:#1a2022;--line:#303b3d;--ink:#e2e9e5;--muted:#94a39e;--mint:#b6dccc;--orange:#edb080}
+.adaptation-panel{margin-top:14px;border:1px solid var(--line);border-radius:6px;background:var(--panel)}
+.adaptation-panel summary{padding:15px 18px;cursor:pointer;font-weight:550;display:flex;gap:18px;justify-content:space-between;list-style:revert}
+.adaptation-panel summary:focus-visible{outline:2px solid var(--mint);outline-offset:3px}
+#adaptation-summary{font-size:11px;color:var(--orange);font-weight:400}
+.adaptation-scope,.adaptation-footnote{padding:0 18px;font-size:11px;line-height:1.8;color:var(--muted)}
+.adaptation-items{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:1px;background:var(--line);border-top:1px solid var(--line);border-bottom:1px solid var(--line)}
+.adaptation-row{padding:15px 18px;background:var(--panel);min-width:0}
+.adaptation-title{display:flex;align-items:baseline;justify-content:space-between;gap:12px}
+.adaptation-title strong{font-size:12px;font-weight:550;overflow-wrap:anywhere}
+.adaptation-badge{font-size:10px;white-space:nowrap;color:var(--mint)}
+.adaptation-badge.missing{color:#ef9b8d}.adaptation-badge.approximate,.adaptation-badge.unverified{color:var(--orange)}
+.adaptation-row p{font-size:11px;line-height:1.75;margin:9px 0 0;color:var(--ink)}
+.adaptation-row .adaptation-action{color:var(--muted)}
+.adaptation-buttons{display:flex;gap:8px;flex-wrap:wrap;margin-top:12px}.adaptation-buttons button{font-size:11px;padding:6px 9px}
+@media(max-width:800px){.adaptation-items{grid-template-columns:1fr}.adaptation-panel summary{align-items:flex-start;flex-direction:column;gap:7px}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:13px 'Segoe UI','Microsoft YaHei UI',sans-serif}button,select{font:inherit;color:inherit;background:var(--panel);border:1px solid #465250;border-radius:5px}button{padding:9px 14px;cursor:pointer}button:hover{border-color:var(--mint)}button:disabled,select:disabled{opacity:.45;cursor:default}button span{font-size:18px;margin-right:5px}select{padding:6px 29px 6px 10px;max-width:160px}button:focus-visible,select:focus-visible{outline:2px solid var(--mint);outline-offset:4px}[hidden]{display:none!important}
+.comparison-app{width:min(1680px,100%);margin:auto;padding:25px 30px 12px}header{display:flex;align-items:center;gap:24px;padding-bottom:22px}.scene-title{flex:1;min-width:0}.eyebrow{margin:0 0 9px;font-size:10px;font-weight:600;letter-spacing:1.6px;color:var(--muted)}.eyebrow span{color:#586c63;padding:0 10px}h1{font-size:25px;letter-spacing:.3px;margin:0;font-weight:550}.asset-id{margin:7px 0 0;font-size:11px;color:var(--muted)}.task-context{display:flex;align-items:center;gap:8px;font-size:12px}.source-dot,.engine-dot{width:6px;height:6px;border-radius:50%;background:var(--orange)}.engine-dot{background:var(--mint)}.arrow{margin:0 8px;color:#73867e}
+.viewer{border:1px solid var(--line);border-radius:7px;overflow:hidden;background:#0d1213}.view-toolbar{height:45px;display:flex;gap:12px;align-items:center;padding:0 17px;border-bottom:1px solid var(--line);background:var(--panel);font-size:11px;color:var(--muted)}.live-state{color:var(--ink);flex:1;display:flex;align-items:center;gap:8px}.live-state:before{content:'';display:inline-block;width:5px;height:5px;background:var(--mint);border-radius:50%}.frame-note{padding-left:14px;border-left:1px solid var(--line)}.stage{position:relative;height:clamp(290px,calc(100dvh - 335px),870px);min-height:290px;display:grid;place-items:center;overflow:hidden;background:#0c1112}.comparison{position:relative;overflow:hidden;isolation:isolate;touch-action:none;cursor:ew-resize;background:#0c1112}.engine-view{position:absolute;inset:0;display:grid;place-items:center;pointer-events:none}.render-frame canvas{display:block}.blender-view{position:absolute;inset:0;clip-path:inset(0 calc(100% - var(--split)) 0 0);pointer-events:none}.blender-view img{width:100%;height:100%;display:block;object-fit:fill;user-select:none}.source-label,.engine-label{position:absolute;top:15px;padding:9px 12px;border-radius:4px;display:flex;align-items:center;gap:9px;pointer-events:none;background:#13201be3;box-shadow:0 2px 12px #0002;backdrop-filter:blur(10px);font-size:10px}.source-label{left:15px}.engine-label{right:15px}.source-label b{color:#ffd4af}.engine-label b{color:#d4f5e6}.source-label b,.engine-label b{font-size:12px}.source-label span,.engine-label span{color:#c5d2cc}.divider{position:absolute;top:0;bottom:0;left:var(--split);width:38px;transform:translateX(-50%);cursor:ew-resize;touch-action:none;outline:none}.divider:before{content:'';position:absolute;left:18px;width:2px;height:100%;background:#eef6ec;box-shadow:0 0 8px #0007}.grip{position:absolute;top:50%;left:0;transform:translateY(-50%);width:38px;height:43px;border:1px solid #e8f2e3;border-radius:8px;background:#e8f2e3;box-shadow:0 4px 16px #0618105c;display:flex;align-items:center;justify-content:center;gap:6px;color:#30483c;font-size:23px;font-family:Georgia,serif}.grip i{height:15px;border-left:1px solid #b3c4b8}.divider:focus-visible .grip{outline:3px solid #efbc78;outline-offset:4px}.loading{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:14px;color:var(--muted);padding:35px;text-align:center}.loading p{line-height:1.8;overflow-wrap:anywhere}.loader{width:22px;height:22px;border:1px solid #344a3f;border-top-color:var(--mint);border-radius:50%;animation:spin 1s linear infinite}.loading.error .loader{display:none}@keyframes spin{to{transform:rotate(360deg)}}
+.view-caption{height:38px;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:0 17px;background:var(--panel);font-size:10px;color:var(--muted)}.view-caption>span:first-child{display:flex;align-items:center;gap:8px}.split-symbol{display:inline-block;width:11px;height:11px;border:1px solid #78938a;background:linear-gradient(90deg,#a9cabb 50%,transparent 50%)}.contract-strip{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:0;margin-top:17px;border:1px solid var(--line);border-radius:6px;background:var(--panel)}article{padding:16px 18px;min-width:0}article+article{border-left:1px solid var(--line)}.check-heading{display:flex;align-items:center;gap:9px}.check-number{font-size:10px;color:#687e73;font-variant-numeric:tabular-nums}h2{font-size:13px;font-weight:500;margin:0;flex:1}h2 small{font-size:10px;margin-left:7px;color:var(--muted);font-weight:400}.check-state{font-size:10px;color:var(--muted);white-space:nowrap}.check-state.ok{color:var(--mint)}.check-state.warn{color:#e7c48c}.check-state.error{color:#eda69a}article p{font-size:11px;line-height:1.7;color:var(--muted);margin:11px 0 0}footer{display:flex;justify-content:space-between;gap:12px;align-items:baseline;color:#778a81;font-size:10px}footer p{line-height:1.6;overflow-wrap:anywhere}#revision{white-space:nowrap;font-variant-numeric:tabular-nums}
+@media(min-height:1000px){.comparison-app{padding-top:32px}.stage{height:calc(100dvh - 355px)}}@media(max-width:800px){.comparison-app{padding:18px 16px 10px}.task-context{display:none}header{gap:10px}h1{font-size:22px}.frame-note{display:none}.source-label span,.engine-label span{display:none}.contract-strip{grid-template-columns:1fr}article{padding:12px 16px}article+article{border-left:0;border-top:1px solid var(--line)}article p{margin-top:6px}.view-caption{height:auto;min-height:36px;flex-wrap:wrap;padding:10px 12px}#camera-note{display:none}footer{align-items:flex-start}#revision{display:none}.stage{height:clamp(250px,52dvh,500px);min-height:250px}}
+@media(prefers-reduced-motion:reduce){.loader{animation:none}}
+.confirmation-bar{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-top:14px;padding:14px 18px;border:1px solid var(--line);border-radius:6px;background:var(--panel)}.confirmation-bar strong{font-size:12px;font-weight:550}.confirmation-bar p{color:var(--muted);font-size:11px;line-height:1.7;margin:6px 0 0}.confirmation-bar button{white-space:nowrap;background:#29473d;border-color:#608d78}.native-engine-image{position:absolute;inset:0;width:100%;height:100%;pointer-events:none}.native-engine-pending{position:absolute;inset:0;background:#132021;display:grid;place-content:center;justify-items:center;gap:14px;color:var(--muted);pointer-events:none}.confirmation-bar.confirmed{border-color:#608d78}.stage{height:clamp(290px,calc(100dvh - 440px),870px)}@media(max-width:800px){.task-context{display:flex}.task-context>span,.task-context>label{display:none}.confirmation-bar{align-items:stretch;flex-direction:column;gap:10px}.stage{height:clamp(250px,48dvh,500px)}}
+.comparison{cursor:grab}.comparison.orbiting{cursor:grabbing}.blender-pending{position:absolute;inset:0;background:radial-gradient(ellipse at 25% 50%,#22302e,#131c1d 75%)}.pending-content{position:absolute;left:calc(var(--split)/2);top:50%;transform:translate(-50%,-50%);width:220px;max-width:calc(var(--split) - 24px);display:flex;align-items:center;flex-direction:column;gap:14px;text-align:center;color:var(--muted);font-size:12px;line-height:1.7}.pending-content p{margin:0}.pending-content button{pointer-events:auto;font-size:11px;padding:7px 11px}.blender-pending.error .loader{display:none}.blender-view.pending img{visibility:hidden}

package/dist/stage-public/review.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>场景对齐 · Blender / Three.js</title>
+  <link rel="stylesheet" href="./review.css">
+  <script type="importmap">{"imports":{"three":"./vendor/three170/build/three.module.js","three/addons/":"./vendor/three170/examples/jsm/"}}</script>
+</head>
+<body>
+  <main class="comparison-app">
+    <header>
+      <div class="scene-title"><p class="eyebrow">SCENE ALIGNMENT <span>/</span> 场景对齐</p><h1 id="title">载入当前场景</h1><p id="asset-id" class="asset-id"></p></div>
+      <div class="task-context"><span class="source-dot"></span>Blender<span class="arrow">→</span><label for="target-engine">目标引擎</label><select id="target-engine"><option value="three_js">Three.js</option><option value="godot">Godot 4</option></select></div>
+      <button id="reload" disabled><span aria-hidden="true">↻</span> 重新载入</button>
+    </header>
+    <section class="viewer" aria-label="当前场景的 Blender 与 Three.js 对比">
+      <div class="view-toolbar"><span class="live-state" id="view-state">正在检查场景</span><label for="camera">对比机位</label><select id="camera" disabled><option>参考机位</option></select><span class="frame-note">同机位 · 同画幅</span></div>
+      <div id="stage" class="stage">
+        <div id="comparison" class="comparison" style="--split:50%" hidden>
+          <div id="engine-view" class="engine-view"></div><img id="godot-image" class="native-engine-image" alt="当前机位的 Godot 原生渲染" hidden><div id="godot-pending" class="native-engine-pending" hidden><span class="loader" aria-hidden="true"></span><p id="godot-progress">Godot 正在渲染…</p></div>
+          <div id="blender-view" class="blender-view"><img id="blender-image" alt="当前机位的 Blender 原生渲染" draggable="false"><div id="blender-pending" class="blender-pending" hidden><div class="pending-content"><span class="loader" aria-hidden="true"></span><p id="blender-progress" role="status">正在更新当前视角…</p><button id="retry-preview" hidden>重试当前视角</button></div></div></div>
+          <div class="source-label"><b>Blender</b><span id="blender-label">Cycles · 原生渲染</span></div>
+          <div class="engine-label"><b id="engine-name">Three.js</b><span id="engine-render-label">当前引擎渲染</span></div>
+          <div id="divider" class="divider" role="slider" tabindex="0" aria-label="Blender 与 Three.js 对比滑条" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50" aria-valuetext="左侧 Blender 50%，右侧 Three.js 50%" aria-orientation="horizontal"><span class="grip" aria-hidden="true">‹<i></i>›</span></div>
+        </div>
+        <div class="loading" id="loading"><span class="loader" aria-hidden="true"></span><p id="loading-text">读取当前任务的场景与资产契约…</p></div>
+      </div>
+      <div class="view-caption"><span>左键旋转 · 右键平移 · 滚轮缩放 · 拖动分隔线对比</span><span id="camera-note">共享机位 · Blender 停止拖动后更新</span></div>
+    </section>
+    <details id="adaptation-panel" class="adaptation-panel" hidden>
+      <summary><span>效果转换与待核对项</span><span id="adaptation-summary"></span></summary>
+      <p id="adaptation-scope" class="adaptation-scope"></p>
+      <div id="adaptation-items" class="adaptation-items"></div>
+      <p class="adaptation-footnote">这些记录说明转换方式；是否接受当前视觉效果，由你查看两侧画面后决定。</p>
+    </details>
+    <section class="contract-strip" aria-label="资产契约对齐状态">
+      <article><div class="check-heading"><span class="check-number">01</span><h2>空间 <small>Spatial</small></h2><span id="spatial-state" class="check-state">检查中</span></div><p id="spatial-detail">位置、旋转、尺寸与原点</p></article>
+      <article><div class="check-heading"><span class="check-number">02</span><h2>结构 <small>Structural</small></h2><span id="structural-state" class="check-state">检查中</span></div><p id="structural-detail">场景节点、网格与材质关联</p></article>
+      <article><div class="check-heading"><span class="check-number">03</span><h2>视觉 <small>Appearance</small></h2><span id="appearance-state" class="check-state">检查中</span></div><p id="appearance-detail">材质与显示配方、实际渲染差异</p></article>
+    </section>
+    <section class="confirmation-bar" aria-label="导入前确认"><div><strong id="confirmation-state">导入前必须在 Stage 确认</strong><p id="confirmation-note">Blender 建模完成后，先查看空间、结构、材质和灯光效果，再确认当前版本。修改后需重新确认。</p></div><button id="confirm-asset" disabled>确认当前版本，允许导入</button></section>
+    <footer><p id="status" role="status" aria-live="polite">仅检查当前任务的场景。</p><span id="revision"></span></footer>
+  </main>
+  <script type="module" src="./review-app.js"></script>
+</body>
+</html>