evomeme 0.1.9 → 0.1.10

package/dist/stage-public/app.js

@@ -0,0 +1,759 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { TransformControls } from 'three/addons/controls/TransformControls.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+import {
+  applyContractCamera,
+  findCamera,
+  letterboxElement,
+  makeTurquoiseSkyTexture,
+  rebuildAtmosphere,
+  rebuildContractLights,
+} from './sceneContractRuntime.js';
+
+const RUNTIME_FORWARD = new THREE.Vector3(0, 0, -1);
+const SKY = 0xb7c9d6;
+const SKY_FOG = 0xc5d4de;
+const GRASS = 0x8fa88a;
+const GRID_MAIN = 0x6f856c;
+const GRID_SUB = 0x9bb096;
+
+const els = {
+  list: document.getElementById('package-list'),
+  status: document.getElementById('status'),
+  refresh: document.getElementById('refresh-btn'),
+  inspector: document.getElementById('inspector'),
+  title: document.getElementById('asset-title'),
+  path: document.getElementById('asset-path'),
+  type: document.getElementById('field-type'),
+  forward: document.getElementById('field-forward'),
+  pivot: document.getElementById('field-pivot'),
+  scale: document.getElementById('field-scale'),
+  yaw: document.getElementById('field-yaw'),
+  pitch: document.getElementById('field-pitch'),
+  roll: document.getElementById('field-roll'),
+  notes: document.getElementById('field-notes'),
+  runtimeMeta: document.getElementById('runtime-meta'),
+  save: document.getElementById('save-btn'),
+  exportBtn: document.getElementById('export-btn'),
+  stage: document.querySelector('.stage'),
+  viewport: document.getElementById('viewport'),
+  frame: document.getElementById('viewport-frame'),
+  gizmoBar: document.getElementById('gizmo-bar'),
+  cameraBar: document.getElementById('camera-bar'),
+};
+
+/** @type {{ asset_id: string, asset: any, package_dir: string, model_url?: string, scene_contract_url?: string|null, has_scene_contract?: boolean } | null} */
+let selected = null;
+/** @type {any | null} */
+let sceneContract = null;
+/** @type {THREE.Object3D | null} */
+let currentRoot = null;
+/** @type {THREE.Object3D | null} */
+let currentModel = null;
+/** @type {import('three/addons/loaders/GLTFLoader.js').GLTF | null} */
+let currentGltf = null;
+let syncingFromGizmo = false;
+let activeCameraId = 'reference';
+let contractMode = false;
+
+const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.toneMappingExposure = 1.05;
+els.viewport.appendChild(renderer.domElement);
+
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(SKY);
+scene.fog = new THREE.Fog(SKY_FOG, 80, 420);
+const pmrem = new THREE.PMREMGenerator(renderer);
+scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.015).texture;
+
+const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 500);
+camera.position.set(2.2, 1.6, 2.8);
+
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.enableDamping = true;
+controls.target.set(0, 0.8, 0);
+
+const transformControls = new TransformControls(camera, renderer.domElement);
+transformControls.setMode('rotate');
+transformControls.setSpace('local');
+transformControls.setSize(0.95);
+const transformHelper = transformControls.getHelper();
+scene.add(transformHelper);
+transformControls.enabled = false;
+transformHelper.visible = false;
+
+transformControls.addEventListener('dragging-changed', (event) => {
+  controls.enabled = !event.value && (!contractMode || activeCameraId === 'free');
+  if (!event.value && currentRoot && selected && !contractMode) {
+    syncFormFromObject();
+    updateRuntimeMeta(currentRoot, { ...selected.asset, ...formAssetPatch() });
+  }
+});
+
+transformControls.addEventListener('objectChange', () => {
+  if (!currentRoot || !selected || contractMode) return;
+  if (transformControls.getMode() === 'rotate') {
+    syncFormFromObject();
+    updateRuntimeMeta(currentRoot, { ...selected.asset, ...formAssetPatch() });
+  }
+});
+
+const defaultLightRoot = new THREE.Group();
+defaultLightRoot.name = 'default_lights';
+scene.add(defaultLightRoot);
+defaultLightRoot.add(new THREE.HemisphereLight(0xd7e2ea, 0x8fa88a, 0.95));
+const defaultKey = new THREE.DirectionalLight(0xf2eee6, 0.7);
+defaultKey.position.set(4, 8, 2);
+defaultLightRoot.add(defaultKey);
+const defaultFill = new THREE.DirectionalLight(0xc9d5df, 0.28);
+defaultFill.position.set(-4, 3, -3);
+defaultLightRoot.add(defaultFill);
+
+const contractLightRoot = new THREE.Group();
+contractLightRoot.name = 'contract_lights';
+contractLightRoot.visible = false;
+scene.add(contractLightRoot);
+
+const fxRoot = new THREE.Group();
+fxRoot.name = 'atmosphere_fx';
+fxRoot.visible = false;
+scene.add(fxRoot);
+
+const sky = new THREE.Mesh(
+  new THREE.SphereGeometry(400, 32, 16),
+  new THREE.MeshBasicMaterial({
+    map: makeTurquoiseSkyTexture(),
+    side: THREE.BackSide,
+    depthWrite: false,
+  })
+);
+scene.add(sky);
+
+const ground = new THREE.Mesh(
+  new THREE.CircleGeometry(28, 64),
+  new THREE.MeshStandardMaterial({ color: GRASS, roughness: 0.95, metalness: 0 })
+);
+ground.rotation.x = -Math.PI / 2;
+ground.position.y = -0.001;
+scene.add(ground);
+
+const horizon = new THREE.Mesh(
+  new THREE.RingGeometry(22, 28, 64),
+  new THREE.MeshBasicMaterial({
+    color: SKY_FOG,
+    transparent: true,
+    opacity: 0.45,
+    side: THREE.DoubleSide,
+    depthWrite: false,
+  })
+);
+horizon.rotation.x = -Math.PI / 2;
+horizon.position.y = 0.01;
+scene.add(horizon);
+
+const grid = new THREE.GridHelper(12, 12, GRID_MAIN, GRID_SUB);
+grid.position.y = 0.015;
+for (const mat of Array.isArray(grid.material) ? grid.material : [grid.material]) {
+  mat.transparent = true;
+  mat.opacity = 0.22;
+  mat.depthWrite = false;
+}
+scene.add(grid);
+
+const axis = new THREE.AxesHelper(1.2);
+scene.add(axis);
+
+const loader = new GLTFLoader();
+
+function resize() {
+  if (contractMode && sceneContract) {
+    const cam = findCamera(sceneContract, activeCameraId === 'free' ? 'reference' : activeCameraId);
+    const aspect = cam?.aspect_ratio || 1.88;
+    const { width, height } = letterboxElement(els.frame, els.stage, aspect);
+    camera.aspect = aspect;
+    if (activeCameraId !== 'free' && cam) {
+      camera.fov = cam.vertical_fov_degrees;
+      camera.near = cam.near;
+      camera.far = cam.far;
+    }
+    camera.updateProjectionMatrix();
+    renderer.setSize(width, height, false);
+    return;
+  }
+  els.frame.style.width = '100%';
+  els.frame.style.height = '100%';
+  const { clientWidth: w, clientHeight: h } = els.viewport;
+  camera.aspect = w / Math.max(h, 1);
+  camera.updateProjectionMatrix();
+  renderer.setSize(w, h, false);
+}
+window.addEventListener('resize', resize);
+resize();
+
+function animate() {
+  requestAnimationFrame(animate);
+  // OrbitControls.update() always rewrites camera from spherical lookAt(target).
+  // Skip it while a contract camera is locked, or the authored quaternion is lost.
+  if (!contractMode || activeCameraId === 'free') {
+    controls.update();
+  }
+  const motes = fxRoot.children.find((c) => c.isPoints);
+  if (motes) motes.rotation.y += 0.00035;
+  renderer.render(scene, camera);
+}
+animate();
+
+function axisVector(axisName) {
+  const map = {
+    '+x': [1, 0, 0],
+    '-x': [-1, 0, 0],
+    '+y': [0, 1, 0],
+    '-y': [0, -1, 0],
+    '+z': [0, 0, 1],
+    '-z': [0, 0, -1],
+  };
+  const v = map[axisName] || [0, 0, 1];
+  return new THREE.Vector3(v[0], v[1], v[2]);
+}
+
+function runtimeYaw(forwardAxis) {
+  switch (forwardAxis) {
+    case '+z':
+      return Math.PI;
+    case '-z':
+      return 0;
+    case '+x':
+      return Math.PI / 2;
+    case '-x':
+      return -Math.PI / 2;
+    default:
+      return 0;
+  }
+}
+
+function measureBounds(object) {
+  object.updateMatrixWorld(true);
+  const box = new THREE.Box3().setFromObject(object);
+  return {
+    min: box.min,
+    max: box.max,
+    size: box.getSize(new THREE.Vector3()),
+    center: box.getCenter(new THREE.Vector3()),
+  };
+}
+
+function detachGizmo() {
+  transformControls.detach();
+  transformControls.enabled = false;
+  transformHelper.visible = false;
+  els.gizmoBar.hidden = true;
+}
+
+function attachGizmo(object) {
+  if (contractMode) {
+    detachGizmo();
+    return;
+  }
+  transformControls.attach(object);
+  transformControls.enabled = true;
+  transformHelper.visible = true;
+  els.gizmoBar.hidden = false;
+}
+
+function syncFormFromObject() {
+  if (!currentRoot) return;
+  syncingFromGizmo = true;
+  const forward = els.forward.value || '+z';
+  const euler = new THREE.Euler().setFromQuaternion(currentRoot.quaternion.clone(), 'YXZ');
+  let yawOff = THREE.MathUtils.radToDeg(euler.y - runtimeYaw(forward));
+  yawOff = ((yawOff + 540) % 360) - 180;
+  els.yaw.value = yawOff.toFixed(1);
+  els.pitch.value = THREE.MathUtils.radToDeg(euler.x).toFixed(1);
+  els.roll.value = THREE.MathUtils.radToDeg(euler.z).toFixed(1);
+  syncingFromGizmo = false;
+}
+
+function updateRuntimeMeta(object, asset) {
+  const fitted = measureBounds(object);
+  const yaw =
+    runtimeYaw(asset.forward_axis) + THREE.MathUtils.degToRad(asset.yaw_offset_degrees || 0);
+  const authored = axisVector(asset.forward_axis);
+  const lines = [
+    `authored forward: ${asset.forward_axis}  ${vec(authored)}`,
+    `runtime forward: -Z  ${vec(RUNTIME_FORWARD)}`,
+    `pivot: ${asset.pivot || 'ground_center'}  scale_hint: ${asset.scale_hint_metres ?? 'null'}`,
+    `runtime_yaw_deg: ${THREE.MathUtils.radToDeg(yaw).toFixed(1)}`,
+    `offsets °: yaw ${Number(asset.yaw_offset_degrees || 0).toFixed(1)} / pitch ${Number(asset.pitch_offset_degrees || 0).toFixed(1)} / roll ${Number(asset.roll_offset_degrees || 0).toFixed(1)}`,
+    `bounds_m: ${fitted.size.x.toFixed(2)} × ${fitted.size.y.toFixed(2)} × ${fitted.size.z.toFixed(2)}`,
+    `verified_by: ${asset.verified_by}`,
+    `alignment: ${asset.alignment?.overall_status || 'legacy'} · ready=${Boolean(asset.alignment?.ready)}`,
+  ];
+  if (sceneContract) {
+    lines.push(`scene_contract: ${sceneContract.schema} · cam=${activeCameraId}`);
+    lines.push('appearance: three.js approximation (not Cycles parity)');
+  }
+  els.runtimeMeta.textContent = lines.join('\n');
+}
+
+function setBoardExtrasVisible(visible) {
+  ground.visible = visible;
+  horizon.visible = visible;
+  grid.visible = visible;
+  axis.visible = visible;
+  defaultLightRoot.visible = visible;
+}
+
+function fitEnvironment(radius) {
+  const r = Math.max(radius, 0.5);
+  camera.near = Math.max(r / 800, 0.01);
+  camera.far = Math.max(r * 25, 500);
+  camera.updateProjectionMatrix();
+  if (scene.fog) {
+    scene.fog.near = r * 3.5;
+    scene.fog.far = r * 12;
+  }
+  sky.scale.setScalar(Math.max(r / 40, 1));
+  const groundScale = Math.max((r * 4) / 28, 1);
+  ground.scale.setScalar(groundScale);
+  horizon.scale.setScalar(groundScale);
+  grid.scale.setScalar(Math.max(r / 6, 1));
+  axis.scale.setScalar(Math.max(r / 30, 1));
+  controls.minDistance = Math.max(r * 0.04, 0.05);
+  controls.maxDistance = r * 15;
+}
+
+function frameCamera(object) {
+  const fitted = measureBounds(object);
+  const radius = Math.max(fitted.size.x, fitted.size.y, fitted.size.z, 0.5);
+  fitEnvironment(radius);
+  controls.target.copy(fitted.center);
+  camera.position.set(
+    fitted.center.x + radius * 1.15,
+    fitted.center.y + radius * 0.55,
+    fitted.center.z + radius * 1.35
+  );
+  controls.update();
+}
+
+/**
+ * Follow plugin_client applyCanonicalOrientation + contract rules:
+ * pivot=origin / scale_hint=null → identity root, no recenter, no height normalize.
+ */
+function applyOrientation(object, asset, { frame = false } = {}) {
+  object.rotation.set(0, 0, 0);
+  object.scale.set(1, 1, 1);
+  object.position.set(0, 0, 0);
+  object.updateMatrixWorld(true);
+
+  const recipe = asset.alignment?.ready && asset.alignment?.recipe;
+  if (recipe) {
+    object.position.fromArray(recipe.translation_metres);
+    object.quaternion.fromArray(recipe.rotation_quaternion_xyzw);
+    object.scale.fromArray(recipe.scale_xyz);
+    object.updateMatrixWorld(true);
+    if (frame && !contractMode) frameCamera(object);
+    updateRuntimeMeta(object, asset);
+    return;
+  }
+
+  const pivot = asset.pivot || 'ground_center';
+  let bounds = measureBounds(object);
+
+  if (pivot === 'ground_center' || pivot === 'bounds_center') {
+    object.position.x -= bounds.center.x;
+    object.position.z -= bounds.center.z;
+  }
+  if (pivot === 'ground_center') {
+    object.position.y -= bounds.min.y;
+  } else if (pivot === 'bounds_center') {
+    object.position.y -= bounds.center.y;
+  }
+  // pivot === 'origin' → keep world origin
+
+  const yaw = runtimeYaw(asset.forward_axis) + THREE.MathUtils.degToRad(asset.yaw_offset_degrees || 0);
+  object.rotation.order = 'YXZ';
+  object.rotation.y = yaw;
+  object.rotation.x = THREE.MathUtils.degToRad(asset.pitch_offset_degrees || 0);
+  object.rotation.z = THREE.MathUtils.degToRad(asset.roll_offset_degrees || 0);
+  object.updateMatrixWorld(true);
+
+  if (asset.scale_hint_metres && Number(asset.scale_hint_metres) > 0) {
+    bounds = measureBounds(object);
+    if (bounds.size.y > 1e-6) {
+      object.scale.multiplyScalar(Number(asset.scale_hint_metres) / bounds.size.y);
+      object.updateMatrixWorld(true);
+      if (pivot === 'ground_center') {
+        bounds = measureBounds(object);
+        object.position.y -= bounds.min.y;
+      }
+    }
+  }
+
+  bounds = measureBounds(object);
+  const radius = Math.max(bounds.size.x, bounds.size.y, bounds.size.z, 0.5);
+  if (contractMode) {
+    setBoardExtrasVisible(false);
+    // Keep contract fog/camera; only enlarge sky dome for large maps.
+    sky.scale.setScalar(Math.max(radius / 40, 1));
+    if (sceneContract && activeCameraId !== 'free') {
+      applyContractCamera(camera, controls, findCamera(sceneContract, activeCameraId));
+      resize();
+    }
+  } else if (frame) {
+    setBoardExtrasVisible(true);
+    frameCamera(object);
+  } else {
+    setBoardExtrasVisible(true);
+    fitEnvironment(radius);
+  }
+  updateRuntimeMeta(object, asset);
+}
+
+function enableVertexColors(root) {
+  root.traverse((obj) => {
+    if (!obj.isMesh || !obj.geometry?.attributes?.color) return;
+    const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+    for (const mat of mats) {
+      if (!mat) continue;
+      mat.vertexColors = true;
+      // Meadow materials ship without baseColorFactor; keep albedo neutral so COLOR_0 shows.
+      if (mat.color) mat.color.set(0xffffff);
+      mat.needsUpdate = true;
+    }
+  });
+}
+
+function enableContractPresentation(contract) {
+  contractMode = true;
+  sceneContract = contract;
+  els.frame.classList.add('letterbox');
+  els.cameraBar.hidden = false;
+  detachGizmo();
+  setBoardExtrasVisible(false);
+  defaultLightRoot.visible = false;
+  contractLightRoot.visible = true;
+  fxRoot.visible = true;
+  rebuildContractLights(contractLightRoot, contract);
+  rebuildAtmosphere(fxRoot, contract);
+
+  // Avoid RoomEnvironment washout on vertex-colored untextured meshes.
+  scene.environment = null;
+  const exposure = contract.blender_render?.exposure;
+  renderer.toneMappingExposure = 0.85 + (typeof exposure === 'number' ? exposure : 0.05);
+  if (scene.fog) {
+    scene.fog.color.set(0xb7c6d0);
+    scene.fog.near = 90;
+    scene.fog.far = 420;
+  }
+  sky.scale.setScalar(1);
+  activeCameraId = 'reference';
+  highlightCameraButton('reference');
+  applyContractCamera(camera, controls, findCamera(contract, 'reference'));
+  controls.enabled = false;
+  resize();
+}
+
+function disableContractPresentation() {
+  contractMode = false;
+  sceneContract = null;
+  els.frame.classList.remove('letterbox');
+  els.cameraBar.hidden = true;
+  contractLightRoot.visible = false;
+  fxRoot.visible = false;
+  defaultLightRoot.visible = true;
+  setBoardExtrasVisible(true);
+  scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.015).texture;
+  renderer.toneMappingExposure = 1.0;
+  controls.enabled = true;
+  activeCameraId = 'free';
+  resize();
+}
+
+function highlightCameraButton(id) {
+  for (const btn of els.cameraBar.querySelectorAll('[data-camera]')) {
+    btn.classList.toggle('active', btn.dataset.camera === id);
+  }
+}
+
+function vec(v) {
+  return `(${v.x.toFixed(0)}, ${v.y.toFixed(0)}, ${v.z.toFixed(0)})`;
+}
+
+async function api(pathname, init) {
+  const response = await fetch(pathname, {
+    headers: { 'Content-Type': 'application/json' },
+    ...init,
+  });
+  const data = await response.json();
+  if (!response.ok || data.ok === false) {
+    throw new Error(data.error || `HTTP ${response.status}`);
+  }
+  return data;
+}
+
+async function refreshList() {
+  els.status.textContent = '加载列表…';
+  const data = await api('/api/packages');
+  els.list.innerHTML = '';
+  if (!data.packages.length) {
+    els.status.textContent = '还没有 canonical 包。用 MCP create 或放入 GLB。';
+    return;
+  }
+  for (const item of data.packages) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.dataset.id = item.asset_id;
+    btn.innerHTML = `<span class="id">${item.asset_id}</span><span class="sub">${item.asset.type} · ${item.asset.alignment?.overall_status || 'legacy'} · ${item.asset.verified_by}</span>`;
+    btn.addEventListener('click', () => selectPackage(item.asset_id));
+    els.list.appendChild(btn);
+  }
+  els.status.textContent = `${data.packages.length} 个资产包`;
+  if (selected) highlight(selected.asset_id);
+}
+
+function highlight(assetId) {
+  for (const btn of els.list.querySelectorAll('button')) {
+    btn.classList.toggle('active', btn.dataset.id === assetId);
+  }
+}
+
+function fillForm(asset) {
+  els.title.textContent = asset.asset_id;
+  els.type.value = asset.type || 'prop';
+  els.forward.value = asset.forward_axis || '+z';
+  if (els.pivot) els.pivot.value = asset.pivot || 'ground_center';
+  els.scale.value =
+    asset.scale_hint_metres === null || asset.scale_hint_metres === undefined
+      ? ''
+      : String(asset.scale_hint_metres);
+  els.yaw.value = String(asset.yaw_offset_degrees || 0);
+  els.pitch.value = String(asset.pitch_offset_degrees || 0);
+  els.roll.value = String(asset.roll_offset_degrees || 0);
+  els.notes.value = asset.notes || '';
+}
+
+async function selectPackage(assetId) {
+  if (!assetId) {
+    els.status.textContent = '无效资产 ID';
+    return;
+  }
+  els.status.textContent = `加载 ${assetId}…`;
+  const data = await api(`/api/packages/${encodeURIComponent(assetId)}`);
+  selected = {
+    ...data,
+    asset_id: data.asset_id || data.asset?.asset_id || assetId,
+  };
+  highlight(selected.asset_id);
+  els.inspector.hidden = false;
+  els.path.textContent = data.package_dir;
+  fillForm(data.asset);
+
+  sceneContract = null;
+  if (data.has_scene_contract && data.scene_contract_url) {
+    const contractRes = await fetch(data.scene_contract_url);
+    if (!contractRes.ok) throw new Error(`无法读取 scene.contract.json (${contractRes.status})`);
+    sceneContract = await contractRes.json();
+  }
+
+  await loadModel(data.model_url, data.asset, sceneContract);
+  els.status.textContent = sceneContract
+    ? `已选中 ${selected.asset_id} · 契约相机 ${activeCameraId}`
+    : `已选中 ${selected.asset_id} · 拖动物体轴向手柄`;
+}
+
+async function loadModel(modelUrl, asset, contract) {
+  detachGizmo();
+  if (currentRoot) {
+    scene.remove(currentRoot);
+    disposeObject(currentRoot);
+    currentRoot = null;
+    currentModel = null;
+    currentGltf = null;
+  }
+
+  const gltf = await loader.loadAsync(`${modelUrl}?t=${Date.now()}`);
+  currentGltf = gltf;
+  currentModel = gltf.scene;
+  enableVertexColors(currentModel);
+  currentRoot = new THREE.Group();
+  currentRoot.add(currentModel);
+  scene.add(currentRoot);
+
+  if (contract) {
+    enableContractPresentation(contract);
+    applyOrientation(currentRoot, asset, { frame: false });
+    // Prefer embedded glTF cameras (same transforms as contract) after root is identity.
+    syncCameraFromGltf(gltf, activeCameraId === 'free' ? 'reference' : activeCameraId, contract);
+  } else {
+    disableContractPresentation();
+    applyOrientation(currentRoot, asset, { frame: true });
+    attachGizmo(currentRoot);
+  }
+}
+
+function syncCameraFromGltf(gltf, cameraId, contract) {
+  const camDef = findCamera(contract, cameraId);
+  const index = typeof camDef?.gltf_camera_index === 'number' ? camDef.gltf_camera_index : 0;
+  const embedded = gltf.cameras?.[index];
+  currentRoot?.updateMatrixWorld(true);
+  if (embedded) {
+    embedded.updateWorldMatrix(true, false);
+    const wp = new THREE.Vector3();
+    const wq = new THREE.Quaternion();
+    embedded.getWorldPosition(wp);
+    embedded.getWorldQuaternion(wq);
+    camera.position.copy(wp);
+    camera.quaternion.copy(wq);
+    camera.fov = embedded.fov;
+    camera.near = embedded.near;
+    camera.far = embedded.far;
+    if (camDef?.look_at) controls.target.fromArray(camDef.look_at);
+    resize();
+    return;
+  }
+  applyContractCamera(camera, controls, camDef);
+  resize();
+}
+
+function disposeObject(root) {
+  root.traverse((obj) => {
+    if (obj.geometry) obj.geometry.dispose?.();
+    if (obj.material) {
+      const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+      for (const mat of mats) mat.dispose?.();
+    }
+  });
+}
+
+function formAssetPatch() {
+  const scaleRaw = els.scale.value.trim();
+  const patch = {
+    type: els.type.value,
+    forward_axis: els.forward.value,
+    pivot: els.pivot?.value || 'ground_center',
+    scale_hint_metres: scaleRaw === '' ? null : Number(scaleRaw),
+    yaw_offset_degrees: Number(els.yaw.value) || 0,
+    pitch_offset_degrees: Number(els.pitch.value) || 0,
+    roll_offset_degrees: Number(els.roll.value) || 0,
+    notes: els.notes.value,
+    verified_by: 'user_board',
+  };
+  if (currentRoot) {
+    currentRoot.updateMatrixWorld(true);
+    patch.alignment_recipe = {
+      translation_metres: currentRoot.position.toArray(),
+      rotation_quaternion_xyzw: currentRoot.quaternion.toArray(),
+      scale_xyz: currentRoot.scale.toArray(),
+      algorithm_version: 'evomeme.stage.v2',
+    };
+  }
+  return patch;
+}
+
+els.refresh.addEventListener('click', () => {
+  refreshList().catch((error) => {
+    els.status.textContent = error.message;
+  });
+});
+
+els.save.addEventListener('click', async () => {
+  if (!selected?.asset_id) return;
+  try {
+    els.status.textContent = '保存中…';
+    const data = await api(`/api/packages/${encodeURIComponent(selected.asset_id)}`, {
+      method: 'PUT',
+      body: JSON.stringify(formAssetPatch()),
+    });
+    selected = {
+      ...selected,
+      asset_id: data.asset_id || data.asset?.asset_id || selected.asset_id,
+      asset: data.asset,
+      package_dir: data.package_dir,
+    };
+    fillForm(data.asset);
+    if (currentRoot) applyOrientation(currentRoot, data.asset, { frame: !contractMode });
+    els.status.textContent = '已写入 asset.json 并刷新预览';
+    await refreshList();
+  } catch (error) {
+    els.status.textContent = error.message;
+  }
+});
+
+els.exportBtn.addEventListener('click', async () => {
+  if (!selected?.asset_id) return;
+  try {
+    const data = await api(`/api/packages/${encodeURIComponent(selected.asset_id)}/export`, {
+      method: 'POST',
+      body: '{}',
+    });
+    els.status.textContent = `通用包：${data.export_dir}`;
+    alert(`${data.note}\n\n${data.export_dir}`);
+  } catch (error) {
+    els.status.textContent = error.message;
+  }
+});
+
+for (const el of [els.forward, els.scale, els.yaw, els.pitch, els.roll, els.type, els.pivot].filter(Boolean)) {
+  const onEdit = () => {
+    if (syncingFromGizmo || !currentRoot || !selected) return;
+    applyOrientation(currentRoot, { ...selected.asset, ...formAssetPatch(), alignment: null }, { frame: false });
+  };
+  el.addEventListener('change', onEdit);
+  el.addEventListener('input', onEdit);
+}
+
+els.gizmoBar?.addEventListener('click', (event) => {
+  const target = event.target;
+  if (!(target instanceof HTMLElement)) return;
+  const mode = target.dataset.gizmo;
+  if (mode === 'rotate' || mode === 'translate') {
+    transformControls.setMode(mode);
+    for (const btn of els.gizmoBar.querySelectorAll('[data-gizmo]')) {
+      btn.classList.toggle('active', btn === target);
+    }
+    return;
+  }
+  if (target.dataset.space !== undefined) {
+    const next = transformControls.space === 'local' ? 'world' : 'local';
+    transformControls.setSpace(next);
+    target.textContent = next === 'local' ? '局部' : '世界';
+    target.dataset.space = next;
+  }
+});
+
+els.cameraBar?.addEventListener('click', (event) => {
+  const target = event.target;
+  if (!(target instanceof HTMLElement) || !target.dataset.camera || !sceneContract) return;
+  const id = target.dataset.camera;
+  activeCameraId = id;
+  highlightCameraButton(id);
+  if (id === 'free') {
+    controls.enabled = true;
+    const ref = findCamera(sceneContract, 'reference');
+    if (ref) {
+      camera.fov = ref.vertical_fov_degrees;
+      camera.near = ref.near;
+      camera.far = ref.far;
+      camera.updateProjectionMatrix();
+    }
+    els.status.textContent = '自由观察（轨道）；点 reference 可回到契约构图';
+    return;
+  }
+  controls.enabled = false;
+  if (currentGltf) {
+    syncCameraFromGltf(currentGltf, id, sceneContract);
+  } else {
+    applyContractCamera(camera, controls, findCamera(sceneContract, id));
+    resize();
+  }
+  els.status.textContent = `契约相机：${id}`;
+});
+
+refreshList().catch((error) => {
+  els.status.textContent = error.message;
+});