ice3 0.2.0 → 0.2.2

package/dist/index.js

@@ -315,6 +315,7 @@ var ICEIndexedGeometry = class {
   edgeIndices;
   colors;
   semanticIndices;
+  identity;
   constructor(options) {
     if (!options.id.trim()) {
       throw new TypeError("ICE geometry ID must not be empty");
@@ -343,6 +344,11 @@ var ICEIndexedGeometry = class {
       throw new TypeError("ICE semantic index count must match the vertex count");
     }
     this.id = options.id;
+    this.identity = Object.freeze({
+      geometryId: options.identity?.geometryId ?? options.id,
+      topologyDigest: options.identity?.topologyDigest ?? "",
+      attributeDigest: options.identity?.attributeDigest ?? ""
+    });
     this.positions = options.positions;
     this.indices = options.indices;
     if (options.edgeIndices) {
@@ -376,25 +382,48 @@ var ICEIndexedGeometry = class {
       edgeIndexCount: this.edgeIndices?.length ?? 0,
       colorCount: this.colors ? this.positions.length / 3 : 0,
       ...this.semanticIndices ? { semanticIndexCount: this.semanticIndices.length } : {},
+      ...this.identity.topologyDigest || this.identity.attributeDigest ? { identity: this.identity } : {},
       bounds: this.getBounds()
     };
   }
 };
 
 // packages/core/dist/material/ICEBasicMaterial.js
+var DEFAULT_ROUGHNESS = 0.85;
 var ICEBasicMaterial = class {
   typeId = "ice3:BasicMaterial";
   color;
   edgeColor;
+  shading;
+  map;
+  normalMap;
+  ormMap;
+  metallic;
+  roughness;
+  emissive;
   constructor(options) {
     this.color = options.color;
     this.edgeColor = options.edgeColor;
+    this.shading = options.shading;
+    this.map = options.map;
+    this.normalMap = options.normalMap;
+    this.ormMap = options.ormMap;
+    this.metallic = options.metallic ?? 0;
+    this.roughness = options.roughness ?? DEFAULT_ROUGHNESS;
+    this.emissive = options.emissive;
   }
   toJSON() {
     return {
       typeId: this.typeId,
       color: this.color,
-      ...this.edgeColor ? { edgeColor: this.edgeColor } : {}
+      ...this.edgeColor ? { edgeColor: this.edgeColor } : {},
+      ...this.shading ? { shading: this.shading } : {},
+      ...this.map ? { map: this.map } : {},
+      ...this.normalMap ? { normalMap: this.normalMap } : {},
+      ...this.ormMap ? { ormMap: this.ormMap } : {},
+      ...this.metallic !== 0 ? { metallic: this.metallic } : {},
+      ...this.roughness !== DEFAULT_ROUGHNESS ? { roughness: this.roughness } : {},
+      ...this.emissive ? { emissive: this.emissive } : {}
     };
   }
 };
@@ -426,16 +455,31 @@ var ICEPerspectiveCamera = class {
     this.lookTarget = new ICEVector3(...target);
     return this;
   }
+  setClipPlanes(near, far) {
+    if (!Number.isFinite(near) || !Number.isFinite(far) || near <= 0 || far <= near) {
+      throw new RangeError("Camera near/far values are invalid");
+    }
+    this.near = near;
+    this.far = far;
+    return this;
+  }
   getPosition() {
     return this.eye;
   }
   getTarget() {
     return this.lookTarget;
   }
+  /**
+   * 投影矩阵。屏幕空间效果要从深度重建视空间坐标，光有 viewProjection 不够。
+   */
+  getProjectionMatrix(aspect) {
+    return new ICEMatrix4().perspective(this.fov, aspect, this.near, this.far);
+  }
+  getViewMatrix() {
+    return new ICEMatrix4().lookAt(this.eye, this.lookTarget, new ICEVector3(0, 1, 0));
+  }
   getViewProjectionMatrix(aspect) {
-    const projection = new ICEMatrix4().perspective(this.fov, aspect, this.near, this.far);
-    const view = new ICEMatrix4().lookAt(this.eye, this.lookTarget, new ICEVector3(0, 1, 0));
-    return projection.multiply(view);
+    return this.getProjectionMatrix(aspect).multiply(this.getViewMatrix());
   }
 };
 
@@ -765,6 +809,7 @@ var ICEMesh = class _ICEMesh extends ICENode {
   static fromJSON(value) {
     const geometry = value.geometry;
     const material = value.material;
+    const shading = material.shading === "directional" || material.shading === "flat" || material.shading === "water" ? material.shading : void 0;
     return new _ICEMesh({
       id: value.id,
       displayName: typeof value.displayName === "string" ? value.displayName : value.id,
@@ -781,7 +826,8 @@ var ICEMesh = class _ICEMesh extends ICENode {
       }),
       material: new ICEBasicMaterial({
         color: String(material.color),
-        ...typeof material.edgeColor === "string" ? { edgeColor: material.edgeColor } : {}
+        ...typeof material.edgeColor === "string" ? { edgeColor: material.edgeColor } : {},
+        ...shading ? { shading } : {}
       })
     });
   }
@@ -909,17 +955,26 @@ function isRenderBatch(node) {
 }
 
 // packages/renderer/dist/WebGL2Program.js
-var VERTEX_SOURCE = `
-attribute vec3 a_position;
-attribute vec3 a_color;
-attribute vec4 a_instanceColumn0;
-attribute vec4 a_instanceColumn1;
-attribute vec4 a_instanceColumn2;
-attribute vec4 a_instanceColumn3;
+var LIGHT_DIRECTION = [-0.35, 0.85, 0.4];
+var LIGHTING = Object.freeze({
+  ambient: 0.72,
+  direct: 0.72,
+  sky: 0.18,
+  minimum: 0.92,
+  maximum: 1.42
+});
+var VERTEX_SOURCE = `#version 300 es
+in vec3 a_position;
+in vec3 a_color;
+in vec4 a_instanceColumn0;
+in vec4 a_instanceColumn1;
+in vec4 a_instanceColumn2;
+in vec4 a_instanceColumn3;
 uniform mat4 u_worldViewProjection;
 uniform vec2 u_clipOffset;
 uniform float u_useInstancing;
-varying vec3 v_color;
+out vec3 v_color;
+out vec3 v_worldPosition;
 
 void main() {
   mat4 instanceMatrix = mat4(
@@ -937,17 +992,313 @@ void main() {
   gl_Position = u_worldViewProjection * position;
   gl_Position.xy += u_clipOffset * gl_Position.w;
   v_color = a_color;
+  v_worldPosition = position.xyz;
 }
 `;
-var FRAGMENT_SOURCE = `
+var FRAGMENT_SOURCE = `#version 300 es
 precision highp float;
 uniform vec4 u_color;
+uniform vec4 u_clipPlane;
+uniform float u_pickMode;
 uniform float u_useVertexColor;
-varying vec3 v_color;
+uniform float u_useDirectionalShading;
+uniform float u_waterShading;
+uniform vec3 u_cameraPosition;
+uniform sampler2D u_shadowMap;
+uniform mat4 u_lightViewProjection;
+uniform float u_shadowEnabled;
+uniform float u_shadowNormalOffset;
+uniform float u_shadowDebug;
+uniform sampler2D u_baseColorMap;
+uniform float u_useBaseColorMap;
+uniform vec2 u_uvScale;
+uniform sampler2D u_normalMap;
+uniform float u_useNormalMap;
+uniform sampler2D u_ormMap;
+uniform float u_useOrmMap;
+uniform float u_ormOcclusion;
+uniform float u_ormMetallicRoughness;
+uniform float u_normalScale;
+uniform float u_metallic;
+uniform float u_roughness;
+uniform vec3 u_emissive;
+uniform sampler2D u_sceneDepth;
+uniform float u_useSceneDepth;
+uniform mat4 u_projection;
+uniform vec2 u_viewport;
+uniform vec2 u_clipRange;
+uniform float u_aoRadius;
+uniform float u_aoStrength;
+in vec3 v_color;
+in vec3 v_worldPosition;
+out vec4 outputColor;
+
+// \u7531\u5C4F\u5E55 UV \u4E0E\u6DF1\u5EA6\u7F13\u51B2\u91CD\u5EFA\u89C6\u7A7A\u95F4\u5750\u6807\uFF08\u4E0E WebGL2DepthMath \u7684\u6362\u7B97\u4E00\u81F4\uFF09\u3002
+vec3 viewPositionAt(vec2 uv, float tanHalfFov, float aspect, float near, float far) {
+  float depth = texture(u_sceneDepth, uv).r;
+  float ndcZ = depth * 2.0 - 1.0;
+  float linear = (2.0 * near * far) / (far + near - ndcZ * (far - near));
+  vec2 ndc = uv * 2.0 - 1.0;
+  return vec3(ndc.x * tanHalfFov * aspect * linear, ndc.y * tanHalfFov * linear, -linear);
+}
 
 void main() {
-  gl_FragColor = vec4(
-    u_color.rgb * mix(vec3(1.0), v_color, step(0.5, u_useVertexColor)),
+  // Section plane: discard the half-space on the negative side. A zero plane
+  // (0,0,0,0) evaluates to 0 and keeps everything, so it doubles as "off".
+  if (dot(v_worldPosition, u_clipPlane.xyz) + u_clipPlane.w < 0.0) {
+    discard;
+  }
+  if (u_pickMode > 0.5) {
+    outputColor = u_color;
+    return;
+  }
+  vec3 color = u_color.rgb
+    * mix(vec3(1.0), v_color, step(0.5, u_useVertexColor));
+  vec3 normal = normalize(cross(
+    dFdx(v_worldPosition),
+    dFdy(v_worldPosition)
+  ));
+  // Box-projected UVs make the tangent frame analytic: the projection plane's
+  // two world axes are the tangents, so no vertex tangent channel is needed.
+  vec3 tangent = vec3(0.0);
+  vec3 bitangent = vec3(0.0);
+  vec3 axisWeight = abs(normal);
+  if (axisWeight.x >= axisWeight.y && axisWeight.x >= axisWeight.z) {
+    tangent = vec3(0.0, 0.0, -sign(normal.x));
+    bitangent = vec3(0.0, 1.0, 0.0);
+  } else if (axisWeight.y >= axisWeight.z) {
+    tangent = vec3(1.0, 0.0, 0.0);
+    bitangent = vec3(0.0, 0.0, sign(normal.y));
+  } else {
+    tangent = vec3(sign(normal.z), 0.0, 0.0);
+    bitangent = vec3(0.0, 1.0, 0.0);
+  }
+  // \u4E09\u5F20\u8D34\u56FE\u5171\u7528\u540C\u4E00\u5957\u76D2\u6295\u5F71 UV\uFF1A\u6CD5\u7EBF\u4E3B\u5BFC\u8F74\u51B3\u5B9A\u6295\u5F71\u5E73\u9762\uFF0C\u5355\u4F4D\u662F\u7C73\u3002
+  // \u5199\u4E00\u6B21\u5C31\u591F\u4E86\u2014\u2014\u5E95\u56FE\u3001\u6CD5\u7EBF\u56FE\u3001ORM \u5404\u5199\u4E00\u904D\u8FDF\u65E9\u4F1A\u6F02\u3002
+  vec2 surfaceUv;
+  if (axisWeight.x >= axisWeight.y && axisWeight.x >= axisWeight.z) {
+    surfaceUv = vec2(-sign(normal.x) * v_worldPosition.z, v_worldPosition.y);
+  } else if (axisWeight.y >= axisWeight.z) {
+    surfaceUv = vec2(v_worldPosition.x, sign(normal.y) * v_worldPosition.z);
+  } else {
+    surfaceUv = vec2(sign(normal.z) * v_worldPosition.x, v_worldPosition.y);
+  }
+  surfaceUv *= u_uvScale;
+  if (u_useNormalMap > 0.5) {
+    vec3 sampled = texture(u_normalMap, surfaceUv).xyz * 2.0 - 1.0;
+    sampled.xy *= u_normalScale;
+    normal = normalize(
+      normalize(tangent) * sampled.x
+      + normalize(bitangent) * sampled.y
+      + normal * sampled.z
+    );
+  }
+  // \u4E3B\u5149 + \u534A\u7403\u5929\u5149\u3002\u6CD5\u7EBF\u7531\u5C4F\u5E55\u7A7A\u95F4\u5BFC\u6570\u6C42\u51FA\uFF0C\u671D\u5411\u4E0E\u7ED5\u5E8F\u4E00\u81F4\uFF1A
+  // \u8FCE\u7740\u5149\u7684\u4E00\u9762\u5403\u6EE1\u76F4\u5C04\uFF0C\u80CC\u5149\u9762\u53EA\u7559 35% \u7684\u53CD\u5F39\u5149\uFF0C\u6697\u90E8\u4E0D\u81F3\u4E8E\u7CCA\u6210\u4E00\u7247\u3002
+  vec3 lightDirection = normalize(vec3(${LIGHT_DIRECTION.join(", ")}));
+  float ndl = dot(normal, lightDirection);
+  float key = max(ndl, 0.0) + 0.35 * max(-ndl, 0.0);
+  float sky = 0.5 + 0.5 * normal.y;
+  // ORM\uFF1AR \u906E\u853D\u3001G \u7C97\u7CD9\u5EA6\u3001B \u91D1\u5C5E\u5EA6\uFF0C\u548C glTF \u7684\u6253\u5305\u7EA6\u5B9A\u4E00\u81F4\u3002
+  // \u906E\u853D\u53EA\u538B\u95F4\u63A5\u5149\uFF08\u73AF\u5883\u4E0E\u5929\u5149\uFF09\uFF0C\u76F4\u5C04\u7167\u5EA6\u4E0D\u53D7\u5F71\u54CD\u2014\u2014\u5426\u5219\u9634\u5F71\u548C\u8D34\u56FE\u4F1A\u4E92\u76F8\u6253\u67B6\u3002
+  float surfaceOcclusion = 1.0;
+  float surfaceMetallic = u_metallic;
+  float surfaceRoughness = clamp(u_roughness, 0.04, 1.0);
+  if (u_useOrmMap > 0.5) {
+    vec3 orm = texture(u_ormMap, surfaceUv).rgb;
+    if (u_ormOcclusion > 0.5) surfaceOcclusion = clamp(orm.r, 0.0, 1.0);
+    if (u_ormMetallicRoughness > 0.5) {
+      surfaceRoughness = clamp(surfaceRoughness * orm.g, 0.04, 1.0);
+      surfaceMetallic = clamp(surfaceMetallic * orm.b, 0.0, 1.0);
+    }
+  }
+  // \u76F4\u5C04\u5149\u5F3A\u5EA6\u6309\u771F\u5B9E\u65E5\u7167\u7ED9\uFF1A\u671D\u4E0A\u7684\u9762\u4F1A\u8D85\u8FC7 1\uFF0C\u8FC7\u66DD\u5230\u63A5\u8FD1\u767D\u8272\u662F\u5BF9\u7684\uFF0C
+  // \u4E4B\u524D\u4E0A\u9650\u538B\u5230 1 \u9644\u8FD1\uFF0C\u6574\u4E2A\u5382\u533A\u5C31\u6C38\u8FDC\u6652\u4E0D\u5230\u592A\u9633\uFF0C\u770B\u7740\u53D1\u95F7\u53D1\u6697\u3002
+  float shade = clamp(
+    (${LIGHTING.ambient} + ${LIGHTING.sky} * sky) * surfaceOcclusion
+      + ${LIGHTING.direct} * key,
+    ${LIGHTING.minimum},
+    ${LIGHTING.maximum}
+  );
+  // Base-colour texture. There is no UV vertex channel: the projection is
+  // derived from the surface normal's dominant axis, in metres, which matches
+  // the coordinates Studio writes into exported glTF.
+  if (u_useBaseColorMap > 0.5) {
+    color *= texture(u_baseColorMap, surfaceUv).rgb;
+  }
+  vec3 lit = color * mix(1.0, shade, u_useDirectionalShading);
+
+  // \u8868\u9762\u9897\u7C92\uFF1A\u6309\u4E16\u754C\u5750\u6807\u53D6\u4E24\u5C42\u54C8\u5E0C\uFF0C\u6253\u6563\u6574\u7247\u7EAF\u8272\u5E26\u6765\u7684\u5851\u6599\u611F\u3002
+  // \u5E45\u5EA6\u63A7\u5236\u5728 \xB16% \u5185\uFF0C\u8FDC\u4E86\u770B\u4E0D\u51FA\u3001\u8FD1\u4E86\u6709\u8D28\u611F\uFF0C\u4E0D\u4F1A\u55A7\u5BBE\u593A\u4E3B\u3002
+  vec3 fine = floor(v_worldPosition * 4.5);
+  vec3 coarse = floor(v_worldPosition * 0.42);
+  float grain = fract(sin(dot(fine, vec3(12.9898, 78.233, 37.719))) * 43758.5453);
+  float stain = fract(sin(dot(coarse, vec3(39.346, 11.135, 83.155))) * 24634.6345);
+  // \u4F4E\u9891\u6C61\u6E0D\u8D1F\u8D23\u5927\u9762\u79EF\u4E0D\u5300\uFF0C\u9AD8\u9891\u9897\u7C92\u8D1F\u8D23\u8FD1\u770B\u7684\u624B\u611F\u3002
+  lit *= 0.94 + 0.06 * grain + 0.05 * (stain - 0.5);
+
+  // Liquid surfaces use an analytic Fresnel reflection plus shallow ripple
+  // normals. The effect is opt-in through material shading and remains
+  // independent from any application-specific material naming.
+  if (u_waterShading > 0.5) {
+    float waveA = sin(v_worldPosition.x * 1.1
+      + sin(v_worldPosition.z * 0.43) * 2.0);
+    float waveB = sin(v_worldPosition.z * 1.7
+      + v_worldPosition.x * 0.31);
+    float waveC = sin((v_worldPosition.x + v_worldPosition.z) * 2.3);
+    vec3 rippleNormal = normalize(vec3(
+      waveA * 0.09 + waveC * 0.025,
+      1.0,
+      waveB * 0.09 - waveC * 0.02
+    ));
+    vec3 viewDirection = normalize(u_cameraPosition - v_worldPosition);
+    float facing = clamp(dot(rippleNormal, viewDirection), 0.0, 1.0);
+    float fresnel = pow(1.0 - facing, 2.4);
+    vec3 reflectedSky = vec3(0.22, 0.34, 0.36);
+    vec3 surfaceColor = mix(
+      color,
+      reflectedSky,
+      0.30 + 0.30 * fresnel
+    );
+    surfaceColor *= 0.92 + 0.09 * waveA + 0.05 * waveB;
+    vec3 halfDirection = normalize(lightDirection + viewDirection);
+    float sparkle = pow(
+      max(dot(rippleNormal, halfDirection), 0.0),
+      36.0
+    );
+    lit = mix(lit, surfaceColor * shade, 0.92)
+      + vec3(0.42, 0.52, 0.54) * sparkle * 0.55;
+  }
+
+  // \u5C4F\u5E55\u7A7A\u95F4\u906E\u853D\uFF1A\u5148\u628A\u6DF1\u5EA6\u8FD8\u539F\u6210\u89C6\u7A7A\u95F4\u5750\u6807\uFF0C\u518D\u6309**\u4E16\u754C\u534A\u5F84**\u53D6\u6837\u3002
+  // \u76F4\u63A5\u6BD4\u8F83 NDC \u6DF1\u5EA6\u5DEE\u8868\u8FBE\u4E0D\u4E86"1 \u7C73"\u8FD9\u79CD\u91CF\uFF08\u8FDC\u7AEF\u5343\u5206\u4E4B\u51E0\u5C31\u8DE8\u4E86\u5341\u7C73\uFF09\uFF0C
+  // \u8FD9\u4E5F\u662F SPEC-007 \u524D\u4E09\u8F6E\u5931\u8D25\u7684\u539F\u56E0\u3002
+  if (u_useSceneDepth > 0.5) {
+    vec2 screenUv = gl_FragCoord.xy / u_viewport;
+    float tanHalfFov = 1.0 / u_projection[1][1];
+    float aspect = u_projection[1][1] / u_projection[0][0];
+    float near = u_clipRange.x;
+    float far = u_clipRange.y;
+
+    vec3 centre = viewPositionAt(screenUv, tanHalfFov, aspect, near, far);
+    // \u6CD5\u7EBF\u7531\u89C6\u7A7A\u95F4\u4F4D\u7F6E\u7684\u5C4F\u5E55\u5BFC\u6570\u6C42\u51FA\uFF1A\u51E0\u4F55\u6CA1\u6709\u6CD5\u7EBF\u5C5E\u6027\uFF0C\u4E5F\u4E0D\u9700\u8981\u3002
+    vec3 viewNormal = normalize(cross(dFdx(centre), dFdy(centre)));
+    float centreDepth = -centre.z;
+
+    // \u4E16\u754C\u534A\u5F84\u6362\u7B97\u6210\u50CF\u7D20\u534A\u5F84\uFF1A\u8D8A\u8FDC\u8D8A\u5C0F\uFF0C\u8FD1\u666F\u8FDC\u666F\u624D\u90FD\u6709\u610F\u4E49\u3002
+    float pixelRadius = (u_aoRadius / max(1e-4, centreDepth * tanHalfFov)) * (u_viewport.y * 0.5);
+    // \u4EA4\u9519\u68AF\u5EA6\u566A\u58F0\uFF08IGN\uFF09\u4EE3\u66FF sin \u54C8\u5E0C\uFF1A\u540C\u6837\u662F\u9010\u50CF\u7D20\u6270\u52A8\uFF0C\u4F46\u5B83\u5728\u76F8\u90BB\u50CF\u7D20\u95F4\u662F
+    // \u6E10\u53D8\u800C\u975E\u8DF3\u53D8\uFF0C\u91C7\u6837\u7F3A\u53E3\u770B\u8D77\u6765\u50CF\u7EC6\u5BC6\u6296\u52A8\uFF0C\u4E0D\u50CF\u6912\u76D0\u566A\u70B9\u3002
+    float rotation = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715)))) * 6.2831853;
+
+    // \u4E09\u5708\u53D6\u6837\uFF1A0.35 / 0.65 / 1.0 \u500D\u534A\u5F84\uFF0C\u6743\u91CD 1.0 / 0.7 / 0.45\uFF0C\u5206\u522B\u8D1F\u8D23
+    // \u8D34\u5730\u63A5\u89E6\u3001\u7F1D\u9699\u4E2D\u90E8\u3001\u5927\u9762\u79EF\u5939\u89D2\u3002\u6837\u672C\u6309\u4E0E\u6CD5\u7EBF\u7684\u5939\u89D2\u52A0\u6743\u2014\u2014\u6B63\u5BF9\u7740\u7684\u5E73\u9762
+    // \u4E0D\u8BE5\u88AB\u5468\u56F4\u540C\u6837\u5E73\u7684\u4E1C\u897F\u538B\u6697\uFF0C\u53EA\u6709"\u7ACB\u8D77\u6765\u6321\u4F4F\u6211"\u7684\u624D\u7B97\u6CD5\u3002
+    float occlusion = 0.0;
+    float weightSum = 0.0;
+    for (int ring = 0; ring < 3; ring++) {
+      // \u4E09\u5708\uFF1A\u8D34\u5730\u63A5\u89E6 / \u7F1D\u9699\u4E2D\u90E8 / \u5927\u9762\u79EF\u5939\u89D2\u3002\u6CA1\u6709\u6A21\u7CCA\u901A\u9053\u65F6\uFF0C\u9760\u5708\u5C42\u5206\u644A
+      // \u91C7\u6837\u5BC6\u5EA6\u662F\u538B\u566A\u70B9\u6700\u76F4\u63A5\u7684\u529E\u6CD5\uFF08\u6A21\u7CCA\u8981\u989D\u5916\u7684 FBO \u4E0E\u5168\u5C4F\u901A\u9053\uFF09\u3002
+      float ringScale = ring == 0 ? 0.35 : (ring == 1 ? 0.65 : 1.0);
+      float ringWeight = ring == 0 ? 1.0 : (ring == 1 ? 0.7 : 0.45);
+      for (int i = 0; i < 8; i++) {
+        float angle = rotation + float(i) * 0.7853982 + float(ring) * 0.2618;
+        vec2 offset = vec2(cos(angle), sin(angle)) * pixelRadius * ringScale;
+        vec2 sampleUv = screenUv + offset / u_viewport;
+        if (sampleUv.x < 0.0 || sampleUv.x > 1.0 || sampleUv.y < 0.0 || sampleUv.y > 1.0) continue;
+        vec3 delta = viewPositionAt(sampleUv, tanHalfFov, aspect, near, far) - centre;
+        float distance = length(delta);
+        if (distance < 0.0001 || distance > u_aoRadius) continue;
+        float alignment = dot(delta, viewNormal) / distance;
+        if (alignment <= 0.15) continue;
+        occlusion += ringWeight * alignment;
+        weightSum += ringWeight;
+      }
+    }
+    if (weightSum > 0.0) {
+      occlusion /= weightSum;
+      lit *= 1.0 - clamp(occlusion, 0.0, 1.0) * u_aoStrength;
+    }
+  }
+
+  // \u91D1\u5C5E\u6CA1\u6709\u6F2B\u53CD\u5C04\uFF1A\u5B83\u7684\u989C\u8272\u5168\u90E8\u6765\u81EA\u53CD\u5C04\u3002\u5148\u628A\u6F2B\u53CD\u5C04\u6309 metallic \u6536\u6389\uFF0C
+  // \u518D\u7528\u53CD\u5C04\u9879\u8865\u56DE\u6765\uFF0C\u5426\u5219\u91D1\u5C5E\u548C\u5851\u6599\u5728\u540C\u4E00\u4E2A\u592A\u9633\u4E0B\u53EA\u662F"\u989C\u8272\u4E0D\u540C"\u3002
+  {
+    vec3 viewDirection = normalize(u_cameraPosition - v_worldPosition);
+    vec3 halfVector = normalize(lightDirection + viewDirection);
+    float metallic = clamp(surfaceMetallic, 0.0, 1.0);
+    float roughness = clamp(surfaceRoughness, 0.04, 1.0);
+    vec3 reflectance = mix(vec3(0.04), color, metallic);
+
+    float diffuseGain = 1.0 - metallic * 0.85;
+    float facing = max(dot(normal, lightDirection), 0.0);
+
+    // \u9AD8\u5149\uFF1A\u7C97\u7CD9\u5EA6\u51B3\u5B9A\u53F6\u74E3\u5BBD\u5EA6\u4E0E\u5F3A\u5EA6\uFF08\u6307\u6570 96 \u2192 4\uFF0C\u589E\u76CA 1.0 \u2192 0.18\uFF09\u3002
+    float shininess = mix(96.0, 4.0, roughness * roughness);
+    float highlight = pow(max(dot(normal, halfVector), 0.0), shininess);
+    float specularGain = mix(1.0, 0.18, roughness);
+
+    // \u73AF\u5883\u53CD\u5C04\uFF1A\u6309\u53CD\u5C04\u65B9\u5411\u53D6\u5929\u7A7A/\u5730\u9762\u8272\uFF0C\u63A0\u5C04\u89D2\u518D\u53E0\u4E00\u5C42 Fresnel\u3002
+    // \u53EA\u770B\u6CD5\u7EBF\u7684\u8BDD\uFF0C\u5E73\u8EBA\u7684\u91D1\u5C5E\u4F1A\u548C\u7ACB\u7740\u7684\u91D1\u5C5E\u4E00\u4E2A\u989C\u8272\u2014\u2014\u73B0\u5B9E\u91CC\u524D\u8005\u53CD\u5C04\u5929\u9876\u3001
+    // \u540E\u8005\u53CD\u5C04\u5730\u5E73\u7EBF\uFF0C\u6070\u6070\u662F\u91D1\u5C5E\u6700\u5BB9\u6613\u8FA8\u8BA4\u7684\u7279\u5F81\u3002
+    vec3 reflected = reflect(-viewDirection, normal);
+    float skyMix = clamp(reflected.y * 0.9 + 0.35, 0.0, 1.0);
+    vec3 skyColor = mix(vec3(0.15, 0.16, 0.17), vec3(0.62, 0.72, 0.84), skyMix);
+    float fresnel = pow(1.0 - clamp(dot(normal, viewDirection), 0.0, 1.0), 4.0);
+    float envGain = (0.22 + 0.55 * fresnel) * mix(0.4, 1.0, metallic);
+
+    float litScale = diffuseGain;
+    lit *= litScale;
+    lit += reflectance * (highlight * specularGain * mix(0.35, 1.0, facing)
+      + skyColor * envGain);
+    lit += u_emissive;
+  }
+
+  // \u9634\u5F71\uFF1A\u628A\u4E16\u754C\u5750\u6807\u6295\u5230\u5149\u6E90\u7A7A\u95F4\uFF0C\u4E0E\u6DF1\u5EA6\u56FE\u6BD4\u8F83\u3002\u53D6 3\xD73 \u91C7\u6837\u7684\u5E73\u5747\u505A\u8F7B\u5FAE\u67D4\u5316\u3002
+  // shadowLit \u5728\u8C03\u8BD5\u901A\u9053\u91CC\u76F4\u63A5\u8F93\u51FA\uFF1A1 = \u53D7\u5149\uFF0C0 = \u88AB\u906E\u3002
+  float shadowLit = 1.0;
+  if (u_shadowEnabled > 0.5) {
+    // \u91C7\u6837\u70B9\u6CBF\u6CD5\u7EBF\u63A8\u51FA 1.5 \u4E2A\u7EB9\u7D20\uFF1A\u5E73\u8EBA\u5728\u5149\u91CC\u7684\u9762\uFF08\u5C4B\u9876\u3001\u5730\u9762\uFF09\u5728\u6BCF\u4E2A\u7EB9\u7D20\u5185
+    // \u672C\u8EAB\u5C31\u6709\u6DF1\u5EA6\u5DEE\uFF0C\u9760\u6DF1\u5EA6\u504F\u5DEE\u53BB\u8FFD\u8FD9\u4E2A\u5DEE\u53EA\u4F1A\u8BA9\u5F71\u5B50\u8131\u79BB\u7269\u4F53\uFF08peter-panning\uFF09\u3002
+    // \u628A\u6BD4\u8F83\u70B9\u62AC\u79BB\u8868\u9762\u624D\u662F\u6B63\u89E3\uFF0C\u504F\u79FB\u91CF\u6309\u7EB9\u7D20\u6362\u7B97\uFF0C\u548C\u8D34\u56FE\u5206\u8FA8\u7387\u89E3\u8026\u3002
+    vec3 shadowPosition = v_worldPosition + normal * u_shadowNormalOffset;
+    vec4 lightSpace = u_lightViewProjection * vec4(shadowPosition, 1.0);
+    vec3 projected = lightSpace.xyz / max(lightSpace.w, 1e-5) * 0.5 + 0.5;
+    if (projected.x > 0.002 && projected.x < 0.998
+        && projected.y > 0.002 && projected.y < 0.998
+        && projected.z > 0.0 && projected.z < 1.0) {
+      // \u89C6\u9525\u8D34\u5408\u573A\u666F\u540E\u6DF1\u5EA6\u8DE8\u5EA6\u53EA\u6709\u767E\u7C73\u91CF\u7EA7\uFF0C\u504F\u5DEE\u4E5F\u5C31\u53EF\u4EE5\u6309\u7EB9\u7406\u5355\u5143\u7ED9\u3002
+      // \u9634\u5F71 pass \u53EA\u753B\u80CC\u9762\uFF08cull FRONT\uFF09\uFF0C\u53D7\u5149\u9762\u548C\u6DF1\u5EA6\u56FE\u5929\u7136\u9519\u5F00\uFF0C\u57FA\u6570\u53EF\u4EE5\u5F88\u5C0F\uFF1B
+      // \u659C\u9762\u6700\u654F\u611F\uFF0C\u4ECD\u6309 N\xB7L \u653E\u5927\uFF08\u9634\u5F71\u75E4\u75AE\u4E0E\u9634\u5F71\u8131\u79BB\u4E4B\u95F4\u7684\u90A3\u6761\u7A84\u7F1D\uFF09\u3002
+      float ndlShadow = max(dot(normal, lightDirection), 0.0);
+      float bias = 0.0006 + 0.0012 * (1.0 - ndlShadow);
+      float lit2 = 0.0;
+      vec2 texel = vec2(1.0 / 2048.0);
+      for (int dx = -1; dx <= 1; dx++) {
+        for (int dy = -1; dy <= 1; dy++) {
+          float depth = texture(u_shadowMap, projected.xy + vec2(float(dx), float(dy)) * texel).r;
+          lit2 += projected.z - bias > depth ? 0.0 : 1.0;
+        }
+      }
+      shadowLit = lit2 / 9.0;
+      lit *= mix(0.68, 1.0, shadowLit);
+
+    }
+  }
+  // \u8C03\u8BD5\u901A\u9053\uFF1A?shadowdebug=1 \u770B\u906E\u853D\u5224\u5B9A\uFF0C=2 \u770B\u6DF1\u5EA6\u56FE\u672C\u8EAB\u3002
+  if (u_shadowDebug > 0.5) {
+    if (u_shadowDebug < 1.5) {
+      outputColor = vec4(shadowLit, 0.12, 0.12, 1.0);
+    } else {
+      float stored = texture(u_shadowMap, gl_FragCoord.xy / u_viewport).r;
+      outputColor = vec4(vec3(stored), 1.0);
+    }
+    return;
+  }
+  // \u753B\u5E03\u6309 sRGB \u89E3\u91CA\u5199\u5165\u503C\uFF0C\u800C\u6750\u8D28\u662F\u7EBF\u6027\u7A7A\u95F4\u7684\u5206\u91CF\uFF0C\u5FC5\u987B\u505A\u4E00\u6B21\u7F16\u7801\u3002
+  // \u4E0D\u505A\u7684\u8BDD\u7EBF\u6027 0.017 \u4F1A\u5F53\u4F5C sRGB 0.017 \u663E\u793A\uFF0C\u6DF1\u8272\u6750\u8D28\u5168\u90E8\u584C\u6210\u9ED1\u8272\u3002
+  outputColor = vec4(
+    pow(max(lit, vec3(0.0)), vec3(1.0 / 2.2)),
     u_color.a
   );
 }
@@ -963,7 +1314,37 @@ var WebGL2Program = class _WebGL2Program {
   colorLocation;
   clipOffsetLocation;
   vertexColorLocation;
+  directionalShadingLocation;
+  waterShadingLocation;
+  cameraPositionLocation;
+  shadowMapLocation;
+  lightMatrixLocation;
+  shadowEnabledLocation;
+  shadowNormalOffsetLocation;
+  shadowDebugLocation;
   instancingLocation;
+  pickModeLocation;
+  clipPlaneLocation;
+  baseColorMapLocation;
+  useBaseColorMapLocation;
+  uvScaleLocation;
+  normalMapLocation;
+  ormMapLocation;
+  useOrmMapLocation;
+  ormOcclusionLocation;
+  ormMetallicRoughnessLocation;
+  useNormalMapLocation;
+  normalScaleLocation;
+  metallicLocation;
+  roughnessLocation;
+  emissiveLocation;
+  sceneDepthLocation;
+  useSceneDepthLocation;
+  projectionLocation;
+  viewportLocation;
+  clipRangeLocation;
+  aoRadiusLocation;
+  aoStrengthLocation;
   constructor(gl) {
     this.gl = gl;
     const program = this.createProgram(VERTEX_SOURCE, FRAGMENT_SOURCE);
@@ -971,8 +1352,38 @@ var WebGL2Program = class _WebGL2Program {
     const colorLocation = gl.getUniformLocation(program, "u_color");
     const clipOffsetLocation = gl.getUniformLocation(program, "u_clipOffset");
     const vertexColorLocation = gl.getUniformLocation(program, "u_useVertexColor");
+    const directionalShadingLocation = gl.getUniformLocation(program, "u_useDirectionalShading");
+    const waterShadingLocation = gl.getUniformLocation(program, "u_waterShading");
+    const cameraPositionLocation = gl.getUniformLocation(program, "u_cameraPosition");
     const instancingLocation = gl.getUniformLocation(program, "u_useInstancing");
-    if (!matrixLocation || !colorLocation || !clipOffsetLocation || !vertexColorLocation || !instancingLocation) {
+    const pickModeLocation = gl.getUniformLocation(program, "u_pickMode");
+    const clipPlaneLocation = gl.getUniformLocation(program, "u_clipPlane");
+    const baseColorMapLocation = gl.getUniformLocation(program, "u_baseColorMap");
+    const useBaseColorMapLocation = gl.getUniformLocation(program, "u_useBaseColorMap");
+    const uvScaleLocation = gl.getUniformLocation(program, "u_uvScale");
+    const normalMapLocation = gl.getUniformLocation(program, "u_normalMap");
+    const ormMapLocation = gl.getUniformLocation(program, "u_ormMap");
+    const useOrmMapLocation = gl.getUniformLocation(program, "u_useOrmMap");
+    const ormOcclusionLocation = gl.getUniformLocation(program, "u_ormOcclusion");
+    const ormMetallicRoughnessLocation = gl.getUniformLocation(program, "u_ormMetallicRoughness");
+    const useNormalMapLocation = gl.getUniformLocation(program, "u_useNormalMap");
+    const normalScaleLocation = gl.getUniformLocation(program, "u_normalScale");
+    const metallicLocation = gl.getUniformLocation(program, "u_metallic");
+    const roughnessLocation = gl.getUniformLocation(program, "u_roughness");
+    const emissiveLocation = gl.getUniformLocation(program, "u_emissive");
+    const sceneDepthLocation = gl.getUniformLocation(program, "u_sceneDepth");
+    const useSceneDepthLocation = gl.getUniformLocation(program, "u_useSceneDepth");
+    const projectionLocation = gl.getUniformLocation(program, "u_projection");
+    const viewportLocation = gl.getUniformLocation(program, "u_viewport");
+    const clipRangeLocation = gl.getUniformLocation(program, "u_clipRange");
+    const aoRadiusLocation = gl.getUniformLocation(program, "u_aoRadius");
+    const aoStrengthLocation = gl.getUniformLocation(program, "u_aoStrength");
+    const shadowMapLocation = gl.getUniformLocation(program, "u_shadowMap");
+    const lightMatrixLocation = gl.getUniformLocation(program, "u_lightViewProjection");
+    const shadowEnabledLocation = gl.getUniformLocation(program, "u_shadowEnabled");
+    const shadowNormalOffsetLocation = gl.getUniformLocation(program, "u_shadowNormalOffset");
+    const shadowDebugLocation = gl.getUniformLocation(program, "u_shadowDebug");
+    if (!matrixLocation || !colorLocation || !clipOffsetLocation || !vertexColorLocation || !directionalShadingLocation || !waterShadingLocation || !cameraPositionLocation || !instancingLocation || !pickModeLocation) {
       gl.deleteProgram(program);
       throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", "ICE3_SHADER_LINK_FAILED: shader uniforms are missing");
     }
@@ -981,7 +1392,81 @@ var WebGL2Program = class _WebGL2Program {
     this.colorLocation = colorLocation;
     this.clipOffsetLocation = clipOffsetLocation;
     this.vertexColorLocation = vertexColorLocation;
+    this.directionalShadingLocation = directionalShadingLocation;
+    this.waterShadingLocation = waterShadingLocation;
+    this.cameraPositionLocation = cameraPositionLocation;
+    this.shadowMapLocation = shadowMapLocation;
+    this.lightMatrixLocation = lightMatrixLocation;
+    this.shadowEnabledLocation = shadowEnabledLocation;
+    this.shadowNormalOffsetLocation = shadowNormalOffsetLocation;
+    this.shadowDebugLocation = shadowDebugLocation;
     this.instancingLocation = instancingLocation;
+    this.pickModeLocation = pickModeLocation;
+    this.clipPlaneLocation = clipPlaneLocation;
+    this.baseColorMapLocation = baseColorMapLocation;
+    this.useBaseColorMapLocation = useBaseColorMapLocation;
+    this.uvScaleLocation = uvScaleLocation;
+    this.normalMapLocation = normalMapLocation;
+    this.ormMapLocation = ormMapLocation;
+    this.useOrmMapLocation = useOrmMapLocation;
+    this.ormOcclusionLocation = ormOcclusionLocation;
+    this.ormMetallicRoughnessLocation = ormMetallicRoughnessLocation;
+    this.useNormalMapLocation = useNormalMapLocation;
+    this.normalScaleLocation = normalScaleLocation;
+    this.metallicLocation = metallicLocation;
+    this.roughnessLocation = roughnessLocation;
+    this.emissiveLocation = emissiveLocation;
+    this.sceneDepthLocation = sceneDepthLocation;
+    this.useSceneDepthLocation = useSceneDepthLocation;
+    this.projectionLocation = projectionLocation;
+    this.viewportLocation = viewportLocation;
+    this.clipRangeLocation = clipRangeLocation;
+    this.aoRadiusLocation = aoRadiusLocation;
+    this.aoStrengthLocation = aoStrengthLocation;
+    if (sceneDepthLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(sceneDepthLocation, 2);
+    }
+    if (useSceneDepthLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useSceneDepthLocation, 0);
+    }
+    if (aoRadiusLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(aoRadiusLocation, 2.5);
+    }
+    if (emissiveLocation) {
+      gl.useProgram(program);
+      gl.uniform3f(emissiveLocation, 0, 0, 0);
+    }
+    if (normalMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(normalMapLocation, 1);
+    }
+    if (ormMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(ormMapLocation, 4);
+    }
+    if (useNormalMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useNormalMapLocation, 0);
+    }
+    if (baseColorMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(baseColorMapLocation, 0);
+    }
+    if (useBaseColorMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1f(useBaseColorMapLocation, 0);
+    }
+    if (clipPlaneLocation) {
+      gl.useProgram(program);
+      gl.uniform4f(clipPlaneLocation, 0, 0, 0, 0);
+    }
+    if (shadowMapLocation) {
+      gl.useProgram(program);
+      gl.uniform1i(shadowMapLocation, 3);
+    }
   }
   use() {
     this.gl.useProgram(this.program);
@@ -992,15 +1477,156 @@ var WebGL2Program = class _WebGL2Program {
   setColor(color) {
     this.gl.uniform4f(this.colorLocation, ...color);
   }
+  /**
+   * Bind a base-colour texture to unit 0 and enable sampling. Passing `null`
+   * restores flat shading without touching the bound texture.
+   */
+  setBaseColorMap(texture, scale) {
+    const gl = this.gl;
+    if (!this.useBaseColorMapLocation)
+      return;
+    if (!texture) {
+      gl.uniform1f(this.useBaseColorMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useBaseColorMapLocation, 1);
+    if (this.uvScaleLocation) {
+      gl.uniform2f(this.uvScaleLocation, scale[0], scale[1]);
+    }
+  }
+  /** Bind a tangent-space normal map to unit 1; `null` disables perturbation. */
+  setNormalMap(texture, strength) {
+    const gl = this.gl;
+    if (!this.useNormalMapLocation)
+      return;
+    if (!texture) {
+      gl.uniform1f(this.useNormalMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useNormalMapLocation, 1);
+    if (this.normalScaleLocation) {
+      gl.uniform1f(this.normalScaleLocation, strength);
+    }
+  }
+  /**
+   * Bind the packed ORM map. `occlusion` / `metallicRoughness` describe which
+   * halves of the image are meaningful; both false disables sampling.
+   */
+  setOrmMap(texture, occlusion, metallicRoughness) {
+    const gl = this.gl;
+    if (!this.useOrmMapLocation)
+      return;
+    if (!texture || !occlusion && !metallicRoughness) {
+      gl.uniform1f(this.useOrmMapLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE4);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useOrmMapLocation, 1);
+    if (this.ormOcclusionLocation) {
+      gl.uniform1f(this.ormOcclusionLocation, occlusion ? 1 : 0);
+    }
+    if (this.ormMetallicRoughnessLocation) {
+      gl.uniform1f(this.ormMetallicRoughnessLocation, metallicRoughness ? 1 : 0);
+    }
+  }
+  /** Metallic-roughness factors plus emission for the current draw. */
+  setSurface(metallic, roughness, emissive) {
+    const gl = this.gl;
+    if (this.metallicLocation)
+      gl.uniform1f(this.metallicLocation, metallic);
+    if (this.roughnessLocation)
+      gl.uniform1f(this.roughnessLocation, roughness);
+    if (this.emissiveLocation) {
+      if (emissive)
+        gl.uniform3f(this.emissiveLocation, emissive[0], emissive[1], emissive[2]);
+      else
+        gl.uniform3f(this.emissiveLocation, 0, 0, 0);
+    }
+  }
+  /** 绑定相机深度纹理（unit 2）并传入重建视空间所需的相机参数。 */
+  setSceneDepth(texture, projection, near, far, deviceWidth, deviceHeight) {
+    const gl = this.gl;
+    if (!this.useSceneDepthLocation)
+      return;
+    if (!texture || !projection) {
+      gl.uniform1f(this.useSceneDepthLocation, 0);
+      return;
+    }
+    gl.activeTexture(gl.TEXTURE2);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.uniform1f(this.useSceneDepthLocation, 1);
+    if (this.projectionLocation) {
+      gl.uniformMatrix4fv(this.projectionLocation, false, projection.elements);
+    }
+    if (this.viewportLocation) {
+      gl.uniform2f(this.viewportLocation, deviceWidth, deviceHeight);
+    }
+    if (this.clipRangeLocation) {
+      gl.uniform2f(this.clipRangeLocation, near, far);
+    }
+  }
+  /** 遮蔽半径（米）与强度，供运行时调节。强度 0 等于关闭。 */
+  setOcclusion(radius, strength) {
+    const gl = this.gl;
+    if (this.aoRadiusLocation)
+      gl.uniform1f(this.aoRadiusLocation, radius);
+    if (this.aoStrengthLocation)
+      gl.uniform1f(this.aoStrengthLocation, strength);
+  }
   setClipOffset(x, y) {
     this.gl.uniform2f(this.clipOffsetLocation, x, y);
   }
+  setClipPlane(plane) {
+    if (!this.clipPlaneLocation)
+      return;
+    this.gl.uniform4f(this.clipPlaneLocation, plane[0], plane[1], plane[2], plane[3]);
+  }
   setVertexColors(enabled) {
     this.gl.uniform1f(this.vertexColorLocation, enabled ? 1 : 0);
   }
+  /** 绑定阴影贴图与光源矩阵；关闭时着色器跳过采样。 */
+  setShadow(enabled, texture, matrix, normalOffset = 0, unit = 3) {
+    const gl = this.gl;
+    gl.uniform1f(this.shadowEnabledLocation, enabled && texture && matrix ? 1 : 0);
+    if (!enabled || !texture || !matrix)
+      return;
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    if (this.shadowMapLocation)
+      gl.uniform1i(this.shadowMapLocation, unit);
+    if (this.lightMatrixLocation)
+      gl.uniformMatrix4fv(this.lightMatrixLocation, false, matrix);
+    if (this.shadowNormalOffsetLocation) {
+      gl.uniform1f(this.shadowNormalOffsetLocation, normalOffset);
+    }
+    gl.activeTexture(gl.TEXTURE0);
+  }
+  /** 阴影调试通道：0 关闭，1 输出遮蔽判定，2 输出深度图。 */
+  setShadowDebug(mode) {
+    if (!this.shadowDebugLocation)
+      return;
+    this.gl.uniform1f(this.shadowDebugLocation, mode);
+  }
+  setDirectionalShading(enabled) {
+    this.gl.uniform1f(this.directionalShadingLocation, enabled ? 1 : 0);
+  }
+  setWaterShading(enabled) {
+    this.gl.uniform1f(this.waterShadingLocation, enabled ? 1 : 0);
+  }
+  setCameraPosition(position) {
+    this.gl.uniform3f(this.cameraPositionLocation, ...position);
+  }
   setInstancing(enabled) {
     this.gl.uniform1f(this.instancingLocation, enabled ? 1 : 0);
   }
+  setPickMode(enabled) {
+    this.gl.uniform1f(this.pickModeLocation, enabled ? 1 : 0);
+  }
   dispose() {
     this.gl.deleteProgram(this.program);
   }
@@ -1077,12 +1703,24 @@ function collectInstanceBatches(renderables, output = []) {
         semanticIds: group.map((renderable) => renderable.mesh.selectionId),
         semanticIndices,
         meshIds: group.map((renderable) => renderable.id),
-        materialKey: `${material.color}:${material.edgeColor ?? ""}`
+        materialKey: [
+          material.color,
+          material.edgeColor ?? "",
+          material.shading ?? ""
+        ].join(":")
       });
     }
   }
   return output;
 }
+function renderablesOutsideInstanceBatches(renderables, batches) {
+  const batched = /* @__PURE__ */ new Set();
+  for (const batch of batches) {
+    for (const id of batch.meshIds)
+      batched.add(id);
+  }
+  return renderables.filter((renderable) => !batched.has(renderable.id));
+}
 
 // packages/renderer/dist/WebGL2InstanceBatch.js
 var WebGL2InstanceCache = class {
@@ -1127,10 +1765,10 @@ var WebGL2InstanceCache = class {
     gl.bindBuffer(gl.ARRAY_BUFFER, matrixBuffer);
     gl.bufferData(gl.ARRAY_BUFFER, batch.instanceMatrices, gl.DYNAMIC_DRAW);
     for (let column = 0; column < 4; column += 1) {
-      const location = WebGL2Program.INSTANCE_MATRIX_ATTRIBUTE + column;
-      gl.enableVertexAttribArray(location);
-      gl.vertexAttribPointer(location, 4, gl.FLOAT, false, 64, column * 16);
-      gl.vertexAttribDivisor(location, 1);
+      const location2 = WebGL2Program.INSTANCE_MATRIX_ATTRIBUTE + column;
+      gl.enableVertexAttribArray(location2);
+      gl.vertexAttribPointer(location2, 4, gl.FLOAT, false, 64, column * 16);
+      gl.vertexAttribDivisor(location2, 1);
     }
     gl.bindBuffer(gl.ARRAY_BUFFER, semanticBuffer);
     gl.bufferData(gl.ARRAY_BUFFER, batch.semanticIndices, gl.DYNAMIC_DRAW);
@@ -1199,8 +1837,12 @@ var WebGL2GeometryCache = class {
   entries = /* @__PURE__ */ new Map();
   active = /* @__PURE__ */ new Set();
   pinned = /* @__PURE__ */ new Set();
+  objectKeys = /* @__PURE__ */ new WeakMap();
+  legacyKeys = /* @__PURE__ */ new WeakMap();
+  objectKeySequence = 0;
   gl = null;
   uploads = 0;
+  updatedBytes = 0;
   evictions = 0;
   frameId = 0;
   inactiveGraceFrames;
@@ -1214,12 +1856,24 @@ var WebGL2GeometryCache = class {
   }
   retain(gl, geometry) {
     this.gl = gl;
-    this.active.add(geometry);
-    const existing = this.entries.get(geometry);
+    const key = this.keyFor(geometry);
+    this.active.add(key);
+    const existing = this.entries.get(key);
     if (existing) {
-      existing.lastUsedFrame = this.frameId;
-      return existing;
+      if (this.canReuse(existing, geometry)) {
+        existing.lastUsedFrame = this.frameId;
+        return existing;
+      }
+    }
+    const next = this.createEntry(gl, geometry, key);
+    if (existing) {
+      this.deleteEntry(existing, false);
     }
+    this.entries.set(key, next);
+    this.uploads += 1;
+    return next;
+  }
+  createEntry(gl, geometry, key) {
     const vertexArray = gl.createVertexArray();
     const positionBuffer = gl.createBuffer();
     const triangleIndexBuffer = gl.createBuffer();
@@ -1260,6 +1914,10 @@ var WebGL2GeometryCache = class {
     }
     gl.bindVertexArray(null);
     const entry = {
+      geometry,
+      geometryId: geometry.identity?.geometryId ?? key,
+      attributeDigest: geometry.identity?.attributeDigest ?? "",
+      topologyDigest: geometry.identity?.topologyDigest ?? "",
       vertexArray,
       positionBuffer,
       triangleIndexBuffer,
@@ -1271,28 +1929,33 @@ var WebGL2GeometryCache = class {
       bytes: geometry.positions.byteLength + geometry.indices.byteLength + (geometry.edgeIndices?.byteLength ?? 0) + (geometry.colors?.byteLength ?? 0) + (geometry.semanticIndices?.byteLength ?? 0),
       lastUsedFrame: this.frameId
     };
-    this.entries.set(geometry, entry);
-    this.uploads += 1;
     return entry;
   }
   beginFrame() {
     this.frameId += 1;
     this.active = /* @__PURE__ */ new Set();
   }
-  pin(gl, geometry) {
-    this.pinned.add(geometry);
+  pin(gl, geometry, update) {
+    const key = this.keyFor(geometry);
+    this.pinned.add(key);
+    const existing = this.entries.get(key);
+    if (existing && update && this.sameTopology(existing, geometry)) {
+      this.gl = gl;
+      this.applyPositionUpdate(gl, existing, geometry, update);
+      return existing;
+    }
     const entry = this.retain(gl, geometry);
     this.enforceBudget();
     if (this.totalBytes > this.maxBytes) {
-      this.pinned.delete(geometry);
-      this.deleteEntry(entry);
-      this.entries.delete(geometry);
+      this.pinned.delete(key);
+      this.deleteEntry(entry, false);
+      this.entries.delete(key);
       throw new Error("ICE3_GPU_RESOURCE_FAILED: geometry exceeds the GPU residency budget");
     }
     return entry;
   }
   unpin(geometry) {
-    this.pinned.delete(geometry);
+    this.pinned.delete(this.keyFor(geometry));
   }
   endFrame() {
     for (const [geometry, entry] of this.entries) {
@@ -1327,10 +1990,13 @@ var WebGL2GeometryCache = class {
   get uploadCount() {
     return this.uploads;
   }
+  get updateBytes() {
+    return this.updatedBytes;
+  }
   get evictionCount() {
     return this.evictions;
   }
-  deleteEntry(entry) {
+  deleteEntry(entry, eviction = true) {
     if (!this.gl)
       return;
     this.gl.deleteBuffer(entry.positionBuffer);
@@ -1339,7 +2005,9 @@ var WebGL2GeometryCache = class {
     this.gl.deleteBuffer(entry.colorBuffer);
     this.gl.deleteBuffer(entry.semanticBuffer);
     this.gl.deleteVertexArray(entry.vertexArray);
-    this.evictions += 1;
+    if (eviction) {
+      this.evictions += 1;
+    }
   }
   enforceBudget() {
     let total = this.totalBytes;
@@ -1354,7 +2022,96 @@ var WebGL2GeometryCache = class {
       total -= entry.bytes;
     }
   }
+  applyPositionUpdate(gl, entry, geometry, update) {
+    let updated = 0;
+    try {
+      gl.bindBuffer(gl.ARRAY_BUFFER, entry.positionBuffer);
+      for (const range of update.positionRanges) {
+        if (range.byteOffset % 4 !== 0 || range.byteLength % 4 !== 0 || range.byteOffset + range.byteLength > geometry.positions.byteLength) {
+          throw new Error("invalid position range");
+        }
+        gl.bufferSubData(gl.ARRAY_BUFFER, range.byteOffset, new Uint8Array(geometry.positions.buffer, geometry.positions.byteOffset + range.byteOffset, range.byteLength));
+        updated += range.byteLength;
+      }
+    } catch (error) {
+      throw new Error("ICE3_GPU_RESOURCE_FAILED: geometry update failed", {
+        cause: error
+      });
+    }
+    entry.geometry = geometry;
+    entry.lastUsedFrame = this.frameId;
+    this.updatedBytes += updated;
+  }
+  canReuse(existing, geometry) {
+    if (existing.geometry === geometry) {
+      return true;
+    }
+    if (!this.sameTopology(existing, geometry)) {
+      return false;
+    }
+    const existingDigest = existing.attributeDigest;
+    const nextDigest = geometry.identity?.attributeDigest ?? "";
+    return (existing.geometry.positions === geometry.positions || equalNumberArrays(existing.geometry.positions, geometry.positions)) && equalOptionalNumberArrays(existing.geometry.colors, geometry.colors) && equalOptionalNumberArrays(existing.geometry.semanticIndices, geometry.semanticIndices) && equalOptionalNumberArrays(existing.geometry.edgeIndices, geometry.edgeIndices) || existingDigest !== "" && existingDigest === nextDigest;
+  }
+  sameTopology(existing, geometry) {
+    const existingDigest = existing.topologyDigest;
+    const nextDigest = geometry.identity?.topologyDigest ?? "";
+    return existing.geometry.indices.constructor === geometry.indices.constructor && existing.geometry.indices.length === geometry.indices.length && (existing.geometry.indices === geometry.indices || existingDigest !== "" && existingDigest === nextDigest || equalTypedArrays(existing.geometry.indices, geometry.indices));
+  }
+  keyFor(geometry) {
+    const identity = geometry.identity?.geometryId;
+    if (identity) {
+      return `identity:${identity}`;
+    }
+    const id = geometry.id;
+    if (typeof id === "string" && id.trim()) {
+      const cached = this.legacyKeys.get(geometry);
+      if (cached)
+        return cached;
+      const key2 = [
+        "content",
+        geometry.positions.length,
+        geometry.indices.length,
+        contentFingerprint(geometry.positions),
+        contentFingerprint(geometry.indices),
+        geometry.colors ? contentFingerprint(geometry.colors) : 0,
+        geometry.edgeIndices ? contentFingerprint(geometry.edgeIndices) : 0,
+        geometry.semanticIndices ? contentFingerprint(geometry.semanticIndices) : 0
+      ].join(":");
+      this.legacyKeys.set(geometry, key2);
+      return key2;
+    }
+    const existing = this.objectKeys.get(geometry);
+    if (existing) {
+      return existing;
+    }
+    const key = `object:${this.objectKeySequence}`;
+    this.objectKeySequence += 1;
+    this.objectKeys.set(geometry, key);
+    return key;
+  }
 };
+function equalTypedArrays(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function equalNumberArrays(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function equalOptionalNumberArrays(left, right) {
+  if (left === void 0 || right === void 0) {
+    return left === right;
+  }
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function contentFingerprint(values) {
+  let hash = 2166136261;
+  const bytes = new Uint8Array(values.buffer, values.byteOffset, values.byteLength);
+  for (const byte of bytes) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash;
+}
 
 // packages/renderer/dist/WebGL2PickCodec.js
 var MAX_SELECTION_INDEX = 16777215;
@@ -1561,6 +2318,7 @@ var WebGL2Picker = class {
     gl.depthFunc(gl.LEQUAL);
     gl.disable(gl.BLEND);
     this.program.use();
+    this.program.setPickMode(true);
     this.program.setClipOffset(0, 0);
     this.program.setInstancing(false);
     const aspect = frame.viewport.width / Math.max(frame.viewport.height, 1);
@@ -1706,13 +2464,529 @@ var WebGL2Picker = class {
   }
 };
 
+// packages/renderer/dist/WebGL2Shader.js
+function createShaderProgram(gl, vertexSource, fragmentSource, label) {
+  const vertex = compileShader(gl, gl.VERTEX_SHADER, vertexSource, `${label}:vertex`);
+  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, fragmentSource, `${label}:fragment`);
+  const program = gl.createProgram();
+  if (!program) {
+    throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", `ICE3_SHADER_LINK_FAILED: ${label}: program allocation failed`);
+  }
+  gl.attachShader(program, vertex);
+  gl.attachShader(program, fragment);
+  gl.linkProgram(program);
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    const log = gl.getProgramInfoLog(program) ?? "unknown link error";
+    gl.deleteProgram(program);
+    throw new ICEEngineError("ICE3_SHADER_LINK_FAILED", `ICE3_SHADER_LINK_FAILED: ${label}: ${log}`);
+  }
+  return program;
+}
+function compileShader(gl, type, source, label) {
+  const shader = gl.createShader(type);
+  if (!shader) {
+    throw new ICEEngineError("ICE3_SHADER_COMPILE_FAILED", `ICE3_SHADER_COMPILE_FAILED: ${label}: allocation failed`);
+  }
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader) ?? "unknown compile error";
+    gl.deleteShader(shader);
+    throw new ICEEngineError("ICE3_SHADER_COMPILE_FAILED", `ICE3_SHADER_COMPILE_FAILED: ${label}: ${log}`);
+  }
+  return shader;
+}
+
+// packages/renderer/dist/ShadowFrustum.js
+var SHADOW_LIGHT_DIRECTION = [-0.35, 0.85, 0.4];
+var BOUNDS_PADDING = 0.08;
+function shadowFrustum(bounds, mapSize = 2048) {
+  const box = bounds ?? { min: [-50, -5, -50], max: [650, 60, 650] };
+  const centre = [
+    (box.min[0] + box.max[0]) / 2,
+    (box.min[1] + box.max[1]) / 2,
+    (box.min[2] + box.max[2]) / 2
+  ];
+  const radius = Math.max(1, 0.5 * Math.hypot(box.max[0] - box.min[0], box.max[1] - box.min[1], box.max[2] - box.min[2]));
+  const pad = radius * BOUNDS_PADDING;
+  const direction = normalize2(SHADOW_LIGHT_DIRECTION);
+  const distance2 = radius * 2 + pad * 2;
+  const eye = [
+    centre[0] + direction[0] * distance2,
+    centre[1] + direction[1] * distance2,
+    centre[2] + direction[2] * distance2
+  ];
+  const view = new ICEMatrix4().lookAt(new ICEVector3(eye[0], eye[1], eye[2]), new ICEVector3(centre[0], centre[1], centre[2]), new ICEVector3(0, 1, 0));
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let minZ = Infinity;
+  let maxZ = -Infinity;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const point = new ICEVector3(corner & 1 ? box.max[0] : box.min[0], corner & 2 ? box.max[1] : box.min[1], corner & 4 ? box.max[2] : box.min[2]);
+    const projected = view.transformPoint(point);
+    minX = Math.min(minX, projected[0]);
+    maxX = Math.max(maxX, projected[0]);
+    minY = Math.min(minY, projected[1]);
+    maxY = Math.max(maxY, projected[1]);
+    minZ = Math.min(minZ, projected[2]);
+    maxZ = Math.max(maxZ, projected[2]);
+  }
+  const projection = orthographic(minX - pad, maxX + pad, minY - pad, maxY + pad, -maxZ - pad, -minZ + pad);
+  const width = maxX - minX + pad * 2;
+  const height = maxY - minY + pad * 2;
+  return {
+    matrix: multiply(projection, view.elements),
+    texelWorld: Math.max(width, height) / mapSize
+  };
+}
+function normalize2(value) {
+  const length = Math.hypot(value[0], value[1], value[2]) || 1;
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+function orthographic(left, right, bottom, top, near, far) {
+  const lr = 1 / (left - right);
+  const bt = 1 / (bottom - top);
+  const nf = 1 / (near - far);
+  return [
+    -2 * lr,
+    0,
+    0,
+    0,
+    0,
+    -2 * bt,
+    0,
+    0,
+    0,
+    0,
+    2 * nf,
+    0,
+    (left + right) * lr,
+    (top + bottom) * bt,
+    (far + near) * nf,
+    1
+  ];
+}
+function multiply(a, b) {
+  const out = new Float32Array(16);
+  for (let column = 0; column < 4; column += 1) {
+    for (let row = 0; row < 4; row += 1) {
+      let sum = 0;
+      for (let k = 0; k < 4; k += 1) {
+        sum += (a[k * 4 + row] ?? 0) * (b[column * 4 + k] ?? 0);
+      }
+      out[column * 4 + row] = sum;
+    }
+  }
+  return out;
+}
+
+// packages/renderer/dist/WebGL2ShadowMap.js
+var VERTEX_SOURCE3 = `#version 300 es
+layout(location = 0) in vec3 a_position;
+layout(location = 3) in mat4 a_instanceMatrix;
+uniform mat4 u_matrix;
+uniform float u_useInstancing;
+void main() {
+  vec4 local = vec4(a_position, 1.0);
+  vec4 world = mix(local, a_instanceMatrix * local, u_useInstancing);
+  gl_Position = u_matrix * world;
+}
+`;
+var FRAGMENT_SOURCE3 = `#version 300 es
+precision highp float;
+void main() {
+  // \u53EA\u5199\u6DF1\u5EA6\uFF0C\u989C\u8272\u4E0D\u9700\u8981\u3002
+}
+`;
+var SHADOW_SIZE = 2048;
+var WebGL2ShadowMap = class {
+  gl;
+  /** 最近一次着色器编译/链接失败的原因，供诊断读取。 */
+  lastError = null;
+  framebuffer = null;
+  depthTexture = null;
+  program = null;
+  matrixLocation = null;
+  instancingLocation = null;
+  matrixScratch = new Float32Array(16);
+  texelWorldValue = 1;
+  constructor(gl) {
+    this.gl = gl;
+    this.createResources();
+  }
+  /** 深度纹理，供主着色器采样。 */
+  get texture() {
+    return this.depthTexture;
+  }
+  get matrix() {
+    return this.matrixScratch;
+  }
+  /** 一个深度纹素在世界空间的边长（米）。法线偏移按它换算，别用魔数。 */
+  get texelWorld() {
+    return this.texelWorldValue;
+  }
+  /**
+   * 按场景包围盒拟合视锥。每帧调用没有意义——场景内容不变时矩阵也不会变，
+   * 所以由调用方决定何时重算（包围盒变化或首帧）。
+   */
+  setBounds(bounds) {
+    const frustum = shadowFrustum(bounds, SHADOW_SIZE);
+    this.matrixScratch.set(frustum.matrix);
+    this.texelWorldValue = frustum.texelWorld;
+  }
+  /** 绑定阴影帧缓冲，返回是否成功。 */
+  begin() {
+    const gl = this.gl;
+    if (!this.framebuffer || !this.program)
+      return false;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, SHADOW_SIZE, SHADOW_SIZE);
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+    gl.clear(gl.DEPTH_BUFFER_BIT);
+    gl.enable(gl.DEPTH_TEST);
+    gl.disable(gl.CULL_FACE);
+    gl.useProgram(this.program);
+    gl.uniformMatrix4fv(this.matrixLocation, false, this.matrixScratch);
+    gl.uniform1f(this.instancingLocation, 1);
+    return true;
+  }
+  /**
+   * 非实例化绘制：矩阵换成 `lightViewProjection × world`，顶点位置直接当世界坐标用。
+   *
+   * 阴影通道原先只会画实例化批次，瓦片（渲染批次）与落单网格因此完全不投影。
+   * 补这两条路径靠的就是这个入口——和 `WebGL2SceneDepth` 同一套写法。
+   */
+  setMatrix(matrix) {
+    this.gl.uniformMatrix4fv(this.matrixLocation, false, matrix);
+  }
+  setInstancing(enabled) {
+    this.gl.uniform1f(this.instancingLocation, enabled ? 1 : 0);
+  }
+  /** 解绑，恢复默认帧缓冲。 */
+  end(width, height) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.disable(gl.CULL_FACE);
+    gl.enable(gl.POLYGON_OFFSET_FILL);
+    gl.viewport(0, 0, width, height);
+  }
+  dispose() {
+    const gl = this.gl;
+    if (this.depthTexture)
+      gl.deleteTexture(this.depthTexture);
+    if (this.framebuffer)
+      gl.deleteFramebuffer(this.framebuffer);
+    if (this.program)
+      gl.deleteProgram(this.program);
+    this.depthTexture = null;
+    this.framebuffer = null;
+    this.program = null;
+  }
+  createResources() {
+    const gl = this.gl;
+    this.depthTexture = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, this.depthTexture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.DEPTH_COMPONENT24, SHADOW_SIZE, SHADOW_SIZE, 0, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, null);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    this.framebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.depthTexture, 0);
+    gl.drawBuffers([gl.NONE]);
+    gl.readBuffer(gl.NONE);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    this.program = this.createProgram(VERTEX_SOURCE3, FRAGMENT_SOURCE3);
+    this.matrixLocation = this.program ? gl.getUniformLocation(this.program, "u_matrix") : null;
+    this.instancingLocation = this.program ? gl.getUniformLocation(this.program, "u_useInstancing") : null;
+    this.setBounds(null);
+  }
+  createProgram(vertex, fragment) {
+    try {
+      return createShaderProgram(this.gl, vertex, fragment, "shadow");
+    } catch (error) {
+      this.lastError = error instanceof Error ? error.message : String(error);
+      return null;
+    }
+  }
+};
+
+// packages/renderer/dist/SceneBounds.js
+var localBoundsCache = /* @__PURE__ */ new WeakMap();
+function geometryLocalBounds(geometry) {
+  const cached = localBoundsCache.get(geometry);
+  if (cached)
+    return cached;
+  const positions = geometry.positions;
+  if (!positions || positions.length < 3)
+    return null;
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (let index = 0; index + 2 < positions.length; index += 3) {
+    const x = positions[index];
+    const y = positions[index + 1];
+    const z = positions[index + 2];
+    if (x < minX)
+      minX = x;
+    if (y < minY)
+      minY = y;
+    if (z < minZ)
+      minZ = z;
+    if (x > maxX)
+      maxX = x;
+    if (y > maxY)
+      maxY = y;
+    if (z > maxZ)
+      maxZ = z;
+  }
+  const bounds = { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+  localBoundsCache.set(geometry, bounds);
+  return bounds;
+}
+function accumulateSceneBounds(renderables) {
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  let seen = false;
+  for (const renderable of renderables) {
+    const local = geometryLocalBounds(renderable.mesh.geometry);
+    if (!local)
+      continue;
+    const matrix = renderable.worldMatrix;
+    for (let corner = 0; corner < 8; corner += 1) {
+      const x = corner & 1 ? local.max[0] : local.min[0];
+      const y = corner & 2 ? local.max[1] : local.min[1];
+      const z = corner & 4 ? local.max[2] : local.min[2];
+      const worldX = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+      const worldY = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+      const worldZ = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+      if (worldX < minX)
+        minX = worldX;
+      if (worldY < minY)
+        minY = worldY;
+      if (worldZ < minZ)
+        minZ = worldZ;
+      if (worldX > maxX)
+        maxX = worldX;
+      if (worldY > maxY)
+        maxY = worldY;
+      if (worldZ > maxZ)
+        maxZ = worldZ;
+      seen = true;
+    }
+  }
+  return seen ? { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] } : null;
+}
+
+// packages/renderer/dist/WebGL2SceneDepth.js
+var VERTEX_SOURCE4 = `#version 300 es
+layout(location = 0) in vec3 a_position;
+layout(location = 3) in mat4 a_instanceMatrix;
+uniform mat4 u_matrix;
+uniform float u_useInstancing;
+void main() {
+  vec4 local = vec4(a_position, 1.0);
+  vec4 world = mix(local, a_instanceMatrix * local, u_useInstancing);
+  gl_Position = u_matrix * world;
+}
+`;
+var FRAGMENT_SOURCE4 = `#version 300 es
+precision highp float;
+void main() {}
+`;
+var WebGL2SceneDepth = class {
+  gl;
+  framebuffer;
+  depthTexture = null;
+  program;
+  matrixLocation;
+  instancingLocation;
+  width = 0;
+  height = 0;
+  constructor(gl) {
+    this.gl = gl;
+    this.program = createShaderProgram(gl, VERTEX_SOURCE4, FRAGMENT_SOURCE4, "scene-depth");
+    this.matrixLocation = gl.getUniformLocation(this.program, "u_matrix");
+    this.instancingLocation = gl.getUniformLocation(this.program, "u_useInstancing");
+    const framebuffer = gl.createFramebuffer();
+    if (!framebuffer)
+      throw new Error("ICE3_FRAMEBUFFER_FAILED: scene depth");
+    this.framebuffer = framebuffer;
+  }
+  get texture() {
+    return this.depthTexture;
+  }
+  begin(viewProjection, width, height) {
+    const gl = this.gl;
+    this.ensureTexture(Math.max(1, width), Math.max(1, height));
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.clear(gl.DEPTH_BUFFER_BIT);
+    gl.enable(gl.DEPTH_TEST);
+    gl.useProgram(this.program);
+    gl.uniformMatrix4fv(this.matrixLocation, false, viewProjection);
+    gl.uniform1f(this.instancingLocation, 0);
+  }
+  setMatrix(matrix) {
+    this.gl.uniformMatrix4fv(this.matrixLocation, false, matrix);
+  }
+  setInstancing(enabled) {
+    this.gl.uniform1f(this.instancingLocation, enabled ? 1 : 0);
+  }
+  end(width, height) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.enable(gl.POLYGON_OFFSET_FILL);
+    gl.viewport(0, 0, width, height);
+  }
+  dispose() {
+    const gl = this.gl;
+    if (this.depthTexture)
+      gl.deleteTexture(this.depthTexture);
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteProgram(this.program);
+    this.depthTexture = null;
+  }
+  ensureTexture(width, height) {
+    const gl = this.gl;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    if (this.depthTexture && this.width === width && this.height === height) {
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.depthTexture, 0);
+      return;
+    }
+    if (this.depthTexture)
+      gl.deleteTexture(this.depthTexture);
+    this.width = width;
+    this.height = height;
+    const texture = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.DEPTH_COMPONENT24, width, height, 0, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, null);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+    gl.drawBuffers([gl.NONE]);
+    gl.readBuffer(gl.NONE);
+    this.depthTexture = texture;
+  }
+};
+
+// packages/renderer/dist/WebGL2TextureCache.js
+var REPEAT = 10497;
+var fetchImageLoader = async (url) => {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`ICE3_TEXTURE_FETCH_FAILED: ${response.status} ${url}`);
+  }
+  return createImageBitmap(await response.blob());
+};
+var WebGL2TextureCache = class {
+  gl;
+  load;
+  onUpload;
+  entries = /* @__PURE__ */ new Map();
+  disposed = false;
+  constructor(gl, load = fetchImageLoader, onUpload) {
+    this.gl = gl;
+    this.load = load;
+    this.onUpload = onUpload;
+  }
+  /** Texture for `url`, or `null` while it is still loading (or after failure). */
+  texture(url) {
+    if (this.disposed)
+      return null;
+    const existing = this.entries.get(url);
+    if (existing) {
+      return existing.state === "ready" ? existing.texture : null;
+    }
+    this.entries.set(url, { state: "pending" });
+    void this.load(url).then((image) => {
+      if (this.disposed) {
+        image.close?.();
+        return;
+      }
+      const texture = this.upload(image);
+      if (this.disposed) {
+        this.gl.deleteTexture(texture);
+        return;
+      }
+      this.entries.set(url, { state: "ready", texture });
+      this.onUpload?.();
+    }).catch(() => {
+      if (!this.disposed)
+        this.entries.set(url, { state: "failed" });
+    });
+    return null;
+  }
+  stats() {
+    let loaded = 0;
+    let pending = 0;
+    let failed2 = 0;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "ready")
+        loaded += 1;
+      else if (entry.state === "pending")
+        pending += 1;
+      else
+        failed2 += 1;
+    }
+    return { loaded, pending, failed: failed2 };
+  }
+  dispose() {
+    if (this.disposed)
+      return;
+    this.disposed = true;
+    for (const entry of this.entries.values()) {
+      if (entry.state === "ready")
+        this.gl.deleteTexture(entry.texture);
+    }
+    this.entries.clear();
+  }
+  upload(image) {
+    const gl = this.gl;
+    const texture = gl.createTexture();
+    if (!texture) {
+      throw new Error("ICE3_TEXTURE_CREATE_FAILED");
+    }
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, REPEAT);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, REPEAT);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.generateMipmap(gl.TEXTURE_2D);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    image.close?.();
+    return texture;
+  }
+};
+
+// packages/renderer/dist/WebGL2Uv.js
+var DEFAULT_UV_SCALE = [1, 1];
+
 // packages/renderer/dist/Color.js
 var COLOR_CACHE_LIMIT = 128;
 var COLOR_CACHE = /* @__PURE__ */ new Map();
 function colorToRgba(color) {
   const normalized = color.startsWith("#") ? color.slice(1) : color;
   const expanded = normalized.length === 3 ? normalized.split("").map((part) => part + part).join("") : normalized;
-  if (!/^[0-9a-fA-F]{6}$/.test(expanded)) {
+  if (!/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(expanded)) {
     throw new Error(`Unsupported ICE basic material color: ${color}`);
   }
   const key = expanded.toLowerCase();
@@ -1723,7 +2997,7 @@ function colorToRgba(color) {
     Number.parseInt(expanded.slice(0, 2), 16) / 255,
     Number.parseInt(expanded.slice(2, 4), 16) / 255,
     Number.parseInt(expanded.slice(4, 6), 16) / 255,
-    1
+    expanded.length === 8 ? Number.parseInt(expanded.slice(6, 8), 16) / 255 : 1
   ]);
   if (COLOR_CACHE.size >= COLOR_CACHE_LIMIT) {
     const oldest = COLOR_CACHE.keys().next().value;
@@ -1781,6 +3055,9 @@ var EDGE_PIXEL_OFFSETS = [
 ];
 var SELECTION_RGBA = [255 / 255, 208 / 255, 0];
 var SELECTION_TINT_ALPHA = 0.65;
+function isTransparentColor(color) {
+  return colorToRgba(color)[3] < 0.999;
+}
 var WebGL2RendererBackend = class {
   capabilities = {
     backend: "webgl2",
@@ -1794,6 +3071,12 @@ var WebGL2RendererBackend = class {
   onContextLost;
   onContextRestored;
   program = null;
+  clipPlane = [0, 0, 0, 0];
+  shadowMap = null;
+  /** 方向光阴影开关：默认关闭，由 `initialize({ shadows })` 或页面地址 `?shadows=` 打开。 */
+  shadowEnabled = false;
+  /** `?shadowdebug=1` 输出遮蔽判定，`=2` 输出深度图；排查阴影问题的唯一可信手段。 */
+  shadowDebug = 0;
   semanticProgram = null;
   geometryCache = null;
   instanceCache = null;
@@ -1821,10 +3104,108 @@ var WebGL2RendererBackend = class {
     gpuEvictions: 0,
     gpuBytes: 0
   };
+  textures = null;
+  sceneDepth = null;
+  occlusionRadius = 2.5;
+  /**
+   * 三圈采样比双圈多找到约 1.7 个亮度点的遮蔽（同参数 96.36 → 94.65），原样沿用到
+   * 默认值就把厂区压得发闷。0.30 是回调后的值：整帧 95.70（无遮蔽 99.59），
+   * 高光像素 878（无遮蔽 1088），接触暗部仍看得见。详见 SPEC-007 第 5.5 节。
+   */
+  occlusionStrength = 0.3;
+  options = null;
+  /**
+   * Bind the material's colour and (if it has one) its base-colour texture.
+   * Called for every opaque/shaded draw so a batched draw and a single mesh draw
+   * cannot drift apart.
+   */
+  applyMaterial(material) {
+    const program = this.program;
+    if (!program)
+      return;
+    program.setColor(colorToRgba(material.color));
+    const map = material.map;
+    const texture = map && this.textures ? this.textures.texture(map.url) : null;
+    program.setBaseColorMap(texture, map?.scale ?? material.ormMap?.scale ?? DEFAULT_UV_SCALE);
+    const normalMap = material.normalMap;
+    const normalTexture = normalMap && this.textures ? this.textures.texture(normalMap.url) : null;
+    program.setNormalMap(normalTexture, normalMap?.strength ?? 1);
+    const ormMap = material.ormMap;
+    const ormTexture = ormMap && this.textures ? this.textures.texture(ormMap.url) : null;
+    program.setOrmMap(ormTexture, ormMap?.occlusion !== false, ormMap?.metallicRoughness !== false);
+    program.setSurface(material.metallic, material.roughness, material.emissive);
+  }
+  /** Edge overlays are line work: never sampled, always flat. */
+  applyEdgeMaterial(material) {
+    const program = this.program;
+    if (!program)
+      return;
+    program.setColor(colorToRgba(material.edgeColor ?? material.color));
+    program.setBaseColorMap(null, DEFAULT_UV_SCALE);
+    program.setNormalMap(null, 1);
+    program.setOrmMap(null, false, false);
+    program.setSurface(0, 0.85, void 0);
+  }
+  /**
+   * `?ao=<radius>,<strength>` 覆盖遮蔽参数（`ao=off` 关闭）。
+   *
+   * 屏幕空间遮蔽的合适参数与场景尺度强相关，靠改代码重编译来找太慢。这里只读一次
+   * 页面地址，纯属调参通道，不参与渲染决策。
+   */
+  readOcclusionOverride() {
+    if (typeof location === "undefined")
+      return;
+    const value = new URLSearchParams(location.search).get("ao");
+    if (!value)
+      return;
+    if (value === "off") {
+      this.occlusionStrength = 0;
+      return;
+    }
+    const parts = value.split(",").map(Number);
+    const radius = parts[0];
+    const strength = parts[1];
+    if (radius !== void 0 && Number.isFinite(radius) && radius > 0) {
+      this.occlusionRadius = radius;
+    }
+    if (strength !== void 0 && Number.isFinite(strength) && strength >= 0) {
+      this.occlusionStrength = strength;
+    }
+  }
+  /**
+   * `?shadows=1` / `?shadows=0` 覆盖阴影开关，与 `?ao` 同属调参通道。
+   *
+   * 阴影是一次额外全场景 pass，默认不开；演示与对比时靠地址栏切换，
+   * 不必为看清"有影子/没影子"重编译一次。
+   */
+  readShadowOverride() {
+    if (typeof location === "undefined")
+      return;
+    const params = new URLSearchParams(location.search);
+    const value = params.get("shadows");
+    if (value !== null) {
+      this.shadowEnabled = value !== "0" && value !== "off";
+    }
+    const debug = Number(params.get("shadowdebug"));
+    this.shadowDebug = Number.isFinite(debug) ? Math.max(0, Math.min(2, Math.trunc(debug))) : 0;
+    if (this.shadowDebug > 0)
+      this.shadowEnabled = true;
+  }
+  ensureTextureCache() {
+    if (this.textures || !this.gl)
+      return;
+    this.textures = new WebGL2TextureCache(this.gl, void 0, () => {
+      this.options?.onUploadReady?.();
+    });
+  }
   handleContextLost = (event) => {
     event.preventDefault();
     this.picker = null;
     this.program = null;
+    this.sceneDepth?.dispose();
+    this.sceneDepth = null;
+    this.shadowMap?.dispose();
+    this.shadowMap = null;
     this.geometryCache?.clear();
     this.geometryCache = null;
     this.instanceCache?.clear();
@@ -1843,6 +3224,7 @@ var WebGL2RendererBackend = class {
     this.onContextRestored?.();
   };
   initialize(options) {
+    this.options = options;
     const gl = options.canvas.getContext("webgl2", {
       alpha: true,
       antialias: true,
@@ -1866,6 +3248,11 @@ var WebGL2RendererBackend = class {
     gl.enable(gl.POLYGON_OFFSET_FILL);
     gl.polygonOffset(2, 4);
     this.createProgram(gl);
+    this.ensureTextureCache();
+    this.sceneDepth = new WebGL2SceneDepth(gl);
+    this.readOcclusionOverride();
+    this.shadowEnabled = options.shadows ?? false;
+    this.readShadowOverride();
     this.canvas.addEventListener("webglcontextlost", this.handleContextLost);
     this.canvas.addEventListener("webglcontextrestored", this.handleContextRestored);
   }
@@ -1888,9 +3275,21 @@ var WebGL2RendererBackend = class {
     }
     this.geometryCache.pin(this.gl, geometry);
   }
+  prepareGeometry(geometry, update) {
+    if (!this.gl || !this.geometryCache) {
+      throw new ICEEngineError("ICE3_ENGINE_NOT_READY", "Renderer is not initialized");
+    }
+    this.geometryCache.pin(this.gl, geometry, update);
+  }
+  releaseGeometry(geometry) {
+    this.geometryCache?.unpin(geometry);
+  }
   releaseBatchGeometry(geometry) {
     this.geometryCache?.unpin(geometry);
   }
+  setClipPlane(plane) {
+    this.clipPlane = plane ? [plane[0], plane[1], plane[2], plane[3]] : [0, 0, 0, 0];
+  }
   render(frame) {
     if (!this.gl || !this.program || !this.geometryCache) {
       throw new ICEEngineError("ICE3_ENGINE_NOT_READY", "Renderer is not initialized");
@@ -1913,7 +3312,12 @@ var WebGL2RendererBackend = class {
       gpuBytes: 0
     };
     this.program.use();
+    this.program.setClipPlane(this.clipPlane);
     this.program.setClipOffset(0, 0);
+    this.program.setDirectionalShading(false);
+    this.program.setWaterShading(false);
+    const cameraPosition = frame.camera.getPosition().toArray();
+    this.program.setCameraPosition(cameraPosition);
     this.geometryCache.beginFrame();
     this.instanceCache.beginFrame();
     this.instancedMeshIds.clear();
@@ -1923,94 +3327,228 @@ var WebGL2RendererBackend = class {
     const renderables = collectRenderables(frame.scene, this.renderablesScratch);
     const instances = collectInstanceBatches(renderables, this.instancesScratch);
     const batches = collectRenderBatches(frame.scene, this.batchesScratch);
+    const standalone = renderablesOutsideInstanceBatches(renderables, instances);
     this.profiler.mark("collect");
-    this.program.setInstancing(true);
-    this.profiler.mark("prepareAndUpload");
-    for (const batch of instances) {
-      const instance = this.instanceCache.retain(gl, this.geometryCache, batch);
-      if (!instance)
-        continue;
-      for (const id of batch.meshIds)
-        this.instancedMeshIds.add(id);
-      mvp.elements.set(viewProjection.elements);
-      this.program.setMatrix(mvp);
-      this.program.setColor(colorToRgba(batch.material.color));
-      this.program.setVertexColors(Boolean(batch.geometry.colors));
-      gl.bindVertexArray(instance.vertexArray);
-      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
-      gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
-      this.frameStats.drawCalls += 1;
-      if (batch.material.edgeColor && instance.edgeCount > 0) {
-        this.program.setVertexColors(false);
-        this.program.setColor(colorToRgba(batch.material.edgeColor));
-        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.edgeIndexBuffer);
-        for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
-          this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
-          gl.drawElementsInstanced(gl.LINES, instance.edgeCount, batch.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
-          this.frameStats.drawCalls += 1;
-        }
+    let aoReady = false;
+    if (this.sceneDepth) {
+      const deviceWidth = Math.max(1, Math.round(frame.viewport.width * this.dpr));
+      const deviceHeight = Math.max(1, Math.round(frame.viewport.height * this.dpr));
+      this.sceneDepth.begin(viewProjection.elements, deviceWidth, deviceHeight);
+      this.sceneDepth.setInstancing(true);
+      for (const batch of instances) {
+        if (isTransparentColor(batch.material.color))
+          continue;
+        const instance = this.instanceCache.retain(gl, this.geometryCache, batch);
+        if (!instance)
+          continue;
+        gl.bindVertexArray(instance.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
+        gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
       }
+      this.sceneDepth.setInstancing(false);
+      for (const draw of batches) {
+        if (isTransparentColor(draw.batch.material.color))
+          continue;
+        world.elements.set(draw.worldMatrix);
+        mvp.elements.set(viewProjection.elements);
+        mvp.multiply(world);
+        this.sceneDepth.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      for (const renderable of standalone) {
+        if (isTransparentColor(renderable.mesh.material.color))
+          continue;
+        world.elements.set(renderable.worldMatrix);
+        mvp.elements.set(viewProjection.elements);
+        mvp.multiply(world);
+        this.sceneDepth.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      this.sceneDepth.end(deviceWidth, deviceHeight);
+      aoReady = true;
+      this.program.use();
     }
-    this.program.setInstancing(false);
-    this.program.setClipOffset(0, 0);
-    for (const draw of batches) {
-      this.program.setClipOffset(0, 0);
-      mvp.elements.set(viewProjection.elements);
-      world.elements.set(draw.worldMatrix);
-      mvp.multiply(world);
-      this.program.setMatrix(mvp);
-      this.program.setColor(colorToRgba(draw.batch.material.color));
-      const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
-      this.program.setVertexColors(Boolean(draw.batch.geometry.colors));
-      gl.bindVertexArray(geometry.vertexArray);
-      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
-      gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
-      this.frameStats.drawCalls += 1;
-      this.frameStats.renderedBatches += 1;
-      if (draw.batch.material.edgeColor) {
-        this.program.setVertexColors(false);
-        this.program.setColor(colorToRgba(draw.batch.material.edgeColor));
-        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
-        for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
-          this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
-          gl.drawElements(gl.LINES, geometry.edgeCount, draw.batch.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
-          this.frameStats.drawCalls += 1;
-        }
+    if (this.shadowEnabled && this.shadowMap) {
+      this.shadowMap.setBounds(accumulateSceneBounds(renderables));
+    }
+    if (this.shadowEnabled && this.shadowMap?.begin()) {
+      const lightViewProjection = this.shadowMap.matrix;
+      for (const batch of instances) {
+        if (isTransparentColor(batch.material.color))
+          continue;
+        const instance = this.instanceCache.retain(gl, this.geometryCache, batch);
+        if (!instance)
+          continue;
+        gl.bindVertexArray(instance.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
+        gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
+      }
+      this.shadowMap.setInstancing(false);
+      for (const draw of batches) {
+        if (isTransparentColor(draw.batch.material.color))
+          continue;
+        world.elements.set(draw.worldMatrix);
+        mvp.elements.set(lightViewProjection);
+        mvp.multiply(world);
+        this.shadowMap.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+      }
+      for (const renderable of standalone) {
+        if (isTransparentColor(renderable.mesh.material.color))
+          continue;
+        world.elements.set(renderable.worldMatrix);
+        mvp.elements.set(lightViewProjection);
+        mvp.multiply(world);
+        this.shadowMap.setMatrix(mvp.elements);
+        const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
       }
+      this.shadowMap.end(frame.viewport.width * this.dpr, frame.viewport.height * this.dpr);
+      this.program.use();
     }
-    for (const renderable of renderables) {
-      if (this.instancedMeshIds.has(renderable.id))
-        continue;
+    if (this.shadowMap) {
+      this.program.use();
+      this.program.setShadow(
+        this.shadowEnabled,
+        this.shadowMap.texture,
+        this.shadowMap.matrix,
+        // 1.5 个纹素：够把平躺在光里的面抬离自身深度，又不会让影子明显离开物体。
+        this.shadowMap.texelWorld * 1.5
+      );
+      this.program.setShadowDebug(this.shadowDebug);
+    }
+    this.program.setSceneDepth(aoReady ? this.sceneDepth.texture : null, frame.camera.getProjectionMatrix(aspect), frame.camera.near, frame.camera.far, Math.max(1, frame.viewport.width * this.dpr), Math.max(1, frame.viewport.height * this.dpr));
+    this.program.setOcclusion(this.occlusionRadius, this.occlusionStrength);
+    for (const transparentPass of [false, true]) {
+      if (transparentPass) {
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+      } else {
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+      }
+      this.program.setInstancing(true);
+      this.profiler.mark("prepareAndUpload");
+      for (const batch of instances) {
+        if (isTransparentColor(batch.material.color) !== transparentPass)
+          continue;
+        const instance = this.instanceCache.retain(gl, this.geometryCache, batch);
+        if (!instance)
+          continue;
+        for (const id of batch.meshIds)
+          this.instancedMeshIds.add(id);
+        mvp.elements.set(viewProjection.elements);
+        this.program.setMatrix(mvp);
+        this.applyMaterial(batch.material);
+        this.program.setVertexColors(Boolean(batch.geometry.colors));
+        this.program.setDirectionalShading(batch.material.shading !== "flat");
+        this.program.setWaterShading(batch.material.shading === "water");
+        gl.bindVertexArray(instance.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.triangleIndexBuffer);
+        gl.drawElementsInstanced(gl.TRIANGLES, instance.triangleCount, batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
+        this.frameStats.drawCalls += 1;
+        if (batch.material.edgeColor && instance.edgeCount > 0) {
+          this.program.setVertexColors(false);
+          this.program.setDirectionalShading(false);
+          this.program.setWaterShading(false);
+          this.applyEdgeMaterial(batch.material);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, instance.edgeIndexBuffer);
+          for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
+            this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
+            gl.drawElementsInstanced(gl.LINES, instance.edgeCount, batch.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0, instance.instanceCount);
+            this.frameStats.drawCalls += 1;
+          }
+        }
+      }
+      this.program.setInstancing(false);
       this.program.setClipOffset(0, 0);
-      mvp.elements.set(viewProjection.elements);
-      world.elements.set(renderable.worldMatrix);
-      mvp.multiply(world);
-      this.program.setMatrix(mvp);
-      this.program.setColor(colorToRgba(renderable.mesh.material.color));
-      const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
-      this.program.setVertexColors(Boolean(renderable.mesh.geometry.colors));
-      gl.bindVertexArray(geometry.vertexArray);
-      gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
-      gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
-      this.frameStats.drawCalls += 1;
-      if (renderable.mesh.material.edgeColor) {
-        this.program.setVertexColors(false);
-        this.program.setColor(colorToRgba(renderable.mesh.material.edgeColor));
-        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
-        for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
-          this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
-          gl.drawElements(gl.LINES, geometry.edgeCount, renderable.mesh.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
-          this.frameStats.drawCalls += 1;
+      for (const draw of batches) {
+        if (isTransparentColor(draw.batch.material.color) !== transparentPass)
+          continue;
+        this.program.setClipOffset(0, 0);
+        mvp.elements.set(viewProjection.elements);
+        world.elements.set(draw.worldMatrix);
+        mvp.multiply(world);
+        this.program.setMatrix(mvp);
+        this.applyMaterial(draw.batch.material);
+        const geometry = this.geometryCache.retain(gl, draw.batch.geometry);
+        this.program.setVertexColors(Boolean(draw.batch.geometry.colors));
+        this.program.setDirectionalShading(draw.batch.material.shading !== "flat");
+        this.program.setWaterShading(draw.batch.material.shading === "water");
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, draw.batch.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+        this.frameStats.drawCalls += 1;
+        this.frameStats.renderedBatches += 1;
+        if (draw.batch.material.edgeColor) {
+          this.program.setVertexColors(false);
+          this.program.setDirectionalShading(false);
+          this.program.setWaterShading(false);
+          this.applyEdgeMaterial(draw.batch.material);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
+          for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
+            this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
+            gl.drawElements(gl.LINES, geometry.edgeCount, draw.batch.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+            this.frameStats.drawCalls += 1;
+          }
+        }
+      }
+      for (const renderable of renderables) {
+        if (isTransparentColor(renderable.mesh.material.color) !== transparentPass)
+          continue;
+        if (this.instancedMeshIds.has(renderable.id))
+          continue;
+        this.program.setClipOffset(0, 0);
+        mvp.elements.set(viewProjection.elements);
+        world.elements.set(renderable.worldMatrix);
+        mvp.multiply(world);
+        this.program.setMatrix(mvp);
+        this.applyMaterial(renderable.mesh.material);
+        const geometry = this.geometryCache.retain(gl, renderable.mesh.geometry);
+        this.program.setVertexColors(Boolean(renderable.mesh.geometry.colors));
+        this.program.setDirectionalShading(renderable.mesh.material.shading !== "flat");
+        this.program.setWaterShading(renderable.mesh.material.shading === "water");
+        gl.bindVertexArray(geometry.vertexArray);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.triangleIndexBuffer);
+        gl.drawElements(gl.TRIANGLES, geometry.triangleCount, renderable.mesh.geometry.indices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+        this.frameStats.drawCalls += 1;
+        if (renderable.mesh.material.edgeColor) {
+          this.program.setVertexColors(false);
+          this.program.setDirectionalShading(false);
+          this.program.setWaterShading(false);
+          this.applyEdgeMaterial(renderable.mesh.material);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, geometry.edgeIndexBuffer);
+          for (const [offsetX, offsetY] of EDGE_PIXEL_OFFSETS) {
+            this.program.setClipOffset(offsetX * clipPixelX, offsetY * clipPixelY);
+            gl.drawElements(gl.LINES, geometry.edgeCount, renderable.mesh.geometry.edgeIndices instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT, 0);
+            this.frameStats.drawCalls += 1;
+          }
         }
+        this.frameStats.renderedMeshes += 1;
       }
-      this.frameStats.renderedMeshes += 1;
     }
+    gl.depthMask(true);
+    gl.disable(gl.BLEND);
     if (frame.selection.length > 0) {
       const selected = new Set(frame.selection);
       gl.enable(gl.BLEND);
       gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
       gl.depthMask(false);
+      gl.polygonOffset(-1, -4);
       this.program.setVertexColors(false);
+      this.program.setDirectionalShading(false);
       this.program.setColor([
         SELECTION_RGBA[0],
         SELECTION_RGBA[1],
@@ -2056,6 +3594,7 @@ var WebGL2RendererBackend = class {
       if (this.semanticProgram) {
         this.semanticProgram.use();
         this.semanticProgram.setInstancing(false);
+        gl.polygonOffset(-1, -4);
         for (const draw of batches) {
           for (let semanticIndex = 0; semanticIndex < draw.batch.semanticSelectionIds.length; semanticIndex += 1) {
             if (!selected.has(draw.batch.semanticSelectionIds[semanticIndex])) {
@@ -2073,6 +3612,7 @@ var WebGL2RendererBackend = class {
           }
         }
         this.semanticProgram.setInstancing(true);
+        gl.polygonOffset(-1, -4);
         mvp.elements.set(viewProjection.elements);
         this.semanticProgram.setMatrix(mvp);
         for (const batch of instances) {
@@ -2089,6 +3629,7 @@ var WebGL2RendererBackend = class {
         }
       }
       gl.depthMask(true);
+      gl.polygonOffset(2, 4);
       gl.disable(gl.BLEND);
       this.program.use();
       this.program.setClipOffset(0, 0);
@@ -2173,6 +3714,7 @@ var WebGL2RendererBackend = class {
     this.geometryCache = new WebGL2GeometryCache();
     this.instanceCache = new WebGL2InstanceCache();
     this.picker = new WebGL2Picker(gl);
+    this.shadowMap = new WebGL2ShadowMap(gl);
   }
 };
 
@@ -2310,8 +3852,8 @@ async function executeProbe(gpu, options) {
       primitive: { topology: "triangle-list" }
     });
     const texture = context.getCurrentTexture();
-    const encoder = device.createCommandEncoder();
-    const pass = encoder.beginRenderPass({
+    const encoder2 = device.createCommandEncoder();
+    const pass = encoder2.beginRenderPass({
       colorAttachments: [{
         view: texture.createView(),
         clearValue: { r: 0, g: 0, b: 0, a: 1 },
@@ -2322,7 +3864,7 @@ async function executeProbe(gpu, options) {
     pass.setPipeline(pipeline);
     pass.draw(3);
     pass.end();
-    device.queue.submit([encoder.finish()]);
+    device.queue.submit([encoder2.finish()]);
     const lost = await Promise.race([
       device.lost.then((info) => info.message || info.reason),
       new Promise((resolve) => {
@@ -2428,9 +3970,13 @@ var WebGPUGeometryCache = class {
   entries = /* @__PURE__ */ new Map();
   active = /* @__PURE__ */ new Set();
   pinned = /* @__PURE__ */ new Set();
+  objectKeys = /* @__PURE__ */ new WeakMap();
+  legacyKeys = /* @__PURE__ */ new WeakMap();
+  objectKeySequence = 0;
   inactiveGraceFrames;
   maxBytes;
   uploads = 0;
+  updatedBytes = 0;
   evictions = 0;
   frameId = 0;
   resourceGeneration = 0;
@@ -2443,12 +3989,23 @@ var WebGPUGeometryCache = class {
     }
   }
   retain(geometry) {
-    this.active.add(geometry);
-    const existing = this.entries.get(geometry);
+    const key = this.keyFor(geometry);
+    this.active.add(key);
+    const existing = this.entries.get(key);
     if (existing) {
-      existing.lastUsedFrame = this.frameId;
-      return existing;
+      if (this.canReuse(existing, geometry)) {
+        existing.lastUsedFrame = this.frameId;
+        return existing;
+      }
+    }
+    const next = this.createEntry(geometry, key);
+    if (existing) {
+      this.deleteEntry(existing, false);
     }
+    this.entries.set(key, next);
+    return next;
+  }
+  createEntry(geometry, key) {
     const buffers = [];
     try {
       const vertexCount = geometry.positions.length / 3;
@@ -2473,6 +4030,10 @@ var WebGPUGeometryCache = class {
       if (semanticBuffer)
         buffers.push(semanticBuffer);
       const entry = {
+        geometry,
+        geometryId: geometry.identity?.geometryId ?? key,
+        attributeDigest: geometry.identity?.attributeDigest ?? "",
+        topologyDigest: geometry.identity?.topologyDigest ?? "",
         vertexBuffer,
         triangleIndexBuffer,
         edgeIndexBuffer,
@@ -2484,7 +4045,6 @@ var WebGPUGeometryCache = class {
         bytes: buffers.reduce((sum, buffer) => sum + buffer.size, 0),
         lastUsedFrame: this.frameId
       };
-      this.entries.set(geometry, entry);
       this.uploads += buffers.length;
       this.resourceGeneration += 1;
       return entry;
@@ -2496,19 +4056,25 @@ var WebGPUGeometryCache = class {
       throw new ICEEngineError("ICE3_GPU_RESOURCE_FAILED", "ICE3_GPU_RESOURCE_FAILED: geometry upload failed", { cause: error });
     }
   }
-  pin(geometry) {
-    this.pinned.add(geometry);
+  pin(geometry, update) {
+    const key = this.keyFor(geometry);
+    this.pinned.add(key);
+    const existing = this.entries.get(key);
+    if (existing && update && this.sameTopology(existing, geometry)) {
+      this.applyPositionUpdate(existing, geometry, update);
+      return existing;
+    }
     const entry = this.retain(geometry);
     this.enforceBudget();
     if (this.totalBytes > this.maxBytes) {
-      this.pinned.delete(geometry);
-      this.deleteEntry(geometry, entry);
+      this.pinned.delete(key);
+      this.deleteEntry(entry);
       throw new ICEEngineError("ICE3_GPU_RESOURCE_FAILED", "ICE3_GPU_RESOURCE_FAILED: geometry exceeds the GPU residency budget");
     }
     return entry;
   }
   unpin(geometry) {
-    this.pinned.delete(geometry);
+    this.pinned.delete(this.keyFor(geometry));
   }
   beginFrame() {
     this.frameId += 1;
@@ -2521,13 +4087,13 @@ var WebGPUGeometryCache = class {
       if (this.frameId - entry.lastUsedFrame < this.inactiveGraceFrames) {
         continue;
       }
-      this.deleteEntry(geometry, entry);
+      this.deleteEntry(entry);
     }
     this.enforceBudget();
   }
   clear() {
     for (const [geometry, entry] of this.entries) {
-      this.deleteEntry(geometry, entry);
+      this.deleteEntry(entry);
     }
     this.active.clear();
     this.pinned.clear();
@@ -2541,6 +4107,9 @@ var WebGPUGeometryCache = class {
   get uploadCount() {
     return this.uploads;
   }
+  get updateBytes() {
+    return this.updatedBytes;
+  }
   get evictionCount() {
     return this.evictions;
   }
@@ -2555,20 +4124,120 @@ var WebGPUGeometryCache = class {
     for (const [geometry, entry] of candidates) {
       if (total <= this.maxBytes)
         break;
-      this.deleteEntry(geometry, entry);
+      this.deleteEntry(entry);
       total -= entry.bytes;
     }
   }
-  deleteEntry(geometry, entry) {
+  deleteEntry(entry, eviction = true) {
     entry.vertexBuffer.destroy();
     entry.triangleIndexBuffer.destroy();
     entry.edgeIndexBuffer?.destroy();
     entry.semanticBuffer?.destroy();
-    this.entries.delete(geometry);
-    this.evictions += 1;
+    for (const [key, candidate] of this.entries) {
+      if (candidate === entry) {
+        this.entries.delete(key);
+        break;
+      }
+    }
+    if (eviction) {
+      this.evictions += 1;
+    }
     this.resourceGeneration += 1;
   }
+  applyPositionUpdate(entry, geometry, update) {
+    let updated = 0;
+    try {
+      for (const range of update.positionRanges) {
+        if (range.byteOffset % 12 !== 0 || range.byteLength % 12 !== 0 || range.byteOffset + range.byteLength > geometry.positions.byteLength) {
+          throw new Error("invalid position range");
+        }
+        const vertexOffset = range.byteOffset / 12;
+        const vertexCount = range.byteLength / 12;
+        const vertices = new Float32Array(vertexCount * 6);
+        const totalVertices = geometry.positions.length / 3;
+        const colorStride = geometry.colors ? geometry.colors.length / totalVertices : 0;
+        for (let index = 0; index < vertexCount; index += 1) {
+          const sourceVertex = vertexOffset + index;
+          vertices[index * 6] = geometry.positions[sourceVertex * 3];
+          vertices[index * 6 + 1] = geometry.positions[sourceVertex * 3 + 1];
+          vertices[index * 6 + 2] = geometry.positions[sourceVertex * 3 + 2];
+          vertices[index * 6 + 3] = geometry.colors?.[sourceVertex * colorStride] ?? 1;
+          vertices[index * 6 + 4] = geometry.colors?.[sourceVertex * colorStride + 1] ?? 1;
+          vertices[index * 6 + 5] = geometry.colors?.[sourceVertex * colorStride + 2] ?? 1;
+        }
+        this.device.queue.writeBuffer(entry.vertexBuffer, range.byteOffset * 2, vertices);
+        updated += range.byteLength;
+      }
+    } catch (error) {
+      throw new ICEEngineError("ICE3_GPU_RESOURCE_FAILED", "ICE3_GPU_RESOURCE_FAILED: geometry update failed", { cause: error });
+    }
+    entry.geometry = geometry;
+    entry.lastUsedFrame = this.frameId;
+    this.updatedBytes += updated;
+  }
+  canReuse(existing, geometry) {
+    if (existing.geometry === geometry) {
+      return true;
+    }
+    if (!this.sameTopology(existing, geometry)) {
+      return false;
+    }
+    return (existing.geometry.positions === geometry.positions || equalNumberArrays2(existing.geometry.positions, geometry.positions)) && equalOptionalNumberArrays2(existing.geometry.colors, geometry.colors) && equalOptionalNumberArrays2(existing.geometry.semanticIndices, geometry.semanticIndices) && equalOptionalNumberArrays2(existing.geometry.edgeIndices, geometry.edgeIndices) || existing.attributeDigest !== "" && existing.attributeDigest === geometry.identity?.attributeDigest;
+  }
+  sameTopology(existing, geometry) {
+    return existing.geometry.indices.constructor === geometry.indices.constructor && existing.geometry.indices.length === geometry.indices.length && (existing.geometry.indices === geometry.indices || existing.topologyDigest !== "" && existing.topologyDigest === geometry.identity?.topologyDigest);
+  }
+  keyFor(geometry) {
+    const identity = geometry.identity?.geometryId;
+    if (identity) {
+      return `identity:${identity}`;
+    }
+    const id = geometry.id;
+    if (typeof id === "string" && id.trim()) {
+      const cached = this.legacyKeys.get(geometry);
+      if (cached)
+        return cached;
+      const key2 = [
+        "content",
+        geometry.positions.length,
+        geometry.indices.length,
+        contentFingerprint2(geometry.positions),
+        contentFingerprint2(geometry.indices),
+        geometry.colors ? contentFingerprint2(geometry.colors) : 0,
+        geometry.edgeIndices ? contentFingerprint2(geometry.edgeIndices) : 0,
+        geometry.semanticIndices ? contentFingerprint2(geometry.semanticIndices) : 0
+      ].join(":");
+      this.legacyKeys.set(geometry, key2);
+      return key2;
+    }
+    const existing = this.objectKeys.get(geometry);
+    if (existing) {
+      return existing;
+    }
+    const key = `object:${this.objectKeySequence}`;
+    this.objectKeySequence += 1;
+    this.objectKeys.set(geometry, key);
+    return key;
+  }
 };
+function contentFingerprint2(values) {
+  let hash = 2166136261;
+  const bytes = new Uint8Array(values.buffer, values.byteOffset, values.byteLength);
+  for (const byte of bytes) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash;
+}
+function equalNumberArrays2(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function equalOptionalNumberArrays2(left, right) {
+  if (left === void 0 || right === void 0) {
+    return left === right;
+  }
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 
 // packages/renderer/dist/WebGPUInstanceCache.js
 var WebGPUInstanceCache = class {
@@ -2664,7 +4333,7 @@ function sameBytes(left, right) {
 
 // packages/renderer/dist/WebGPURenderPipeline.js
 var WEBGPU_UNIFORM_STRIDE = 256;
-var WEBGPU_UNIFORM_BYTES = 128;
+var WEBGPU_UNIFORM_BYTES = 144;
 var SHADER_SOURCE = (selectionMask, storageInstances, indirectInstances) => `
 struct FrameUniforms {
   worldViewProjection: mat4x4<f32>,
@@ -2680,6 +4349,7 @@ struct FrameUniforms {
   useSelectionMask: f32,
   pageBase: f32,
   useIndirect: f32,
+  useLighting: f32,
 }
 
 ${storageInstances ? `
@@ -2696,6 +4366,7 @@ struct VertexOutput {
   @builtin(position) position: vec4<f32>,
   @location(0) color: vec4<f32>,
   @location(1) @interpolate(flat) semantic: u32,
+  @location(2) worldPosition: vec4<f32>,
 }
 
 @group(0) @binding(0) var<uniform> frame: FrameUniforms;
@@ -2748,6 +4419,7 @@ fn vertexMain(
     mix(vec3<f32>(1.0), color, frame.useVertexColor) * frame.color.rgb,
     frame.color.a
   );
+  output.worldPosition = worldPosition;
   output.semantic = select(
     vertexSemantic,
     instanceSemantic,
@@ -2791,7 +4463,24 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
       );
     }
   }` : ""}
-  return input.color;
+  var outputColor = input.color;
+  if (frame.useLighting > 0.5) {
+    let normal = normalize(cross(
+      dpdx(input.worldPosition.xyz),
+      dpdy(input.worldPosition.xyz)
+    ));
+    let lightDirection = normalize(vec3<f32>(-0.35, 0.85, 0.4));
+    let diffuse = dot(normal, lightDirection);
+    let key = max(diffuse, 0.0) + 0.35 * max(-diffuse, 0.0);
+    let sky = 0.5 + 0.5 * normal.y;
+    let shade = clamp(
+      0.72 + 0.72 * key + 0.18 * sky,
+      0.92,
+      1.42
+    );
+    outputColor = vec4<f32>(outputColor.rgb * shade, outputColor.a);
+  }
+  return outputColor;
 }
 `;
 var VERTEX_LAYOUT = [
@@ -2946,7 +4635,14 @@ var WebGPURenderPipeline = class _WebGPURenderPipeline {
         depthStencil: {
           format: "depth24plus",
           depthCompare: "less-equal",
-          depthWriteEnabled: !selection
+          depthWriteEnabled: !selection,
+          // Selected triangles are redrawn after opaque geometry. Pull that
+          // overlay slightly forward instead of competing at an equal depth.
+          ...selection && topology === "triangle-list" ? {
+            depthBias: -1,
+            depthBiasSlopeScale: -1,
+            depthBiasClamp: 0
+          } : {}
         },
         multisample: { count: 1 }
       });
@@ -2995,12 +4691,12 @@ var WebGPUTimestampProfiler = class {
   querySetFor(frameId) {
     return this.slotFor(frameId).querySet;
   }
-  resolveFrame(encoder, frameId) {
+  resolveFrame(encoder2, frameId) {
     const slot = this.slotFor(frameId);
     if (slot.pending) {
       throw new Error("ICE3_TIMESTAMP_SLOT_BUSY");
     }
-    encoder.resolveQuerySet(slot.querySet, 0, 2, slot.buffer, 0);
+    encoder2.resolveQuerySet(slot.querySet, 0, 2, slot.buffer, 0);
     this.pending.push(this.slotIndex(frameId));
     slot.pending = true;
   }
@@ -3168,6 +4864,7 @@ var WebGPUDrawStorage = class {
     this.uniformBuffer[offset + 29] = draw.useSelectionMask ? 1 : 0;
     this.uniformBuffer[offset + 30] = draw.pageBase ?? 0;
     this.uniformBuffer[offset + 31] = draw.useIndirect ? 1 : 0;
+    this.uniformBuffer[offset + 32] = draw.useLighting ? 1 : 0;
     this.count += 1;
     return index;
   }
@@ -3252,13 +4949,13 @@ var WebGPUBundleCache = class {
   get(key, record3) {
     if (this.key === key && this.bundle)
       return this.bundle;
-    const encoder = this.device.createRenderBundleEncoder({
+    const encoder2 = this.device.createRenderBundleEncoder({
       label: `ice3:bundle:${key}`,
       colorFormats: [this.format],
       depthStencilFormat: "depth24plus"
     });
-    record3(encoder);
-    const bundle = encoder.finish();
+    record3(encoder2);
+    const bundle = encoder2.finish();
     this.key = key;
     this.bundle = bundle;
     this.recreations += 1;
@@ -3596,8 +5293,8 @@ var WebGPUVisibilityEncoder = class _WebGPUVisibilityEncoder {
     this.entries.set(page.buffer, entries);
     return entry;
   }
-  encode(encoder, entry, page, uniformBuffer, uniformOffset) {
-    encoder.clearBuffer(entry.indirectBuffer, 4, 4);
+  encode(encoder2, entry, page, uniformBuffer, uniformOffset) {
+    encoder2.clearBuffer(entry.indirectBuffer, 4, 4);
     const bindGroup = this.device.createBindGroup({
       label: "ice3:visibility-bindings",
       layout: this.bindGroupLayout,
@@ -3628,7 +5325,7 @@ var WebGPUVisibilityEncoder = class _WebGPUVisibilityEncoder {
         }
       ]
     });
-    const pass = encoder.beginComputePass({ label: "ice3:visibility-pass" });
+    const pass = encoder2.beginComputePass({ label: "ice3:visibility-pass" });
     pass.setPipeline(this.pipeline);
     pass.setBindGroup(0, bindGroup, [uniformOffset]);
     pass.dispatchWorkgroups(Math.ceil(page.instanceCount / 64));
@@ -3640,9 +5337,9 @@ var WebGPUVisibilityEncoder = class _WebGPUVisibilityEncoder {
       size: 4,
       usage: 1 | 8
     });
-    const encoder = this.device.createCommandEncoder();
-    encoder.copyBufferToBuffer(entry.indirectBuffer, 4, readback, 0, 4);
-    this.device.queue.submit([encoder.finish()]);
+    const encoder2 = this.device.createCommandEncoder();
+    encoder2.copyBufferToBuffer(entry.indirectBuffer, 4, readback, 0, 4);
+    this.device.queue.submit([encoder2.finish()]);
     try {
       await readback.mapAsync(1);
       const visibleInstances = new Uint32Array(readback.getMappedRange())[0];
@@ -3815,8 +5512,8 @@ var WebGPUPicker = class {
         }
       }]
     });
-    const encoder = this.device.createCommandEncoder();
-    const pass = encoder.beginRenderPass({
+    const encoder2 = this.device.createCommandEncoder();
+    const pass = encoder2.beginRenderPass({
       colorAttachments: [{
         view: this.target.createView(),
         clearValue: { r: 0, g: 0, b: 0, a: 1 },
@@ -3848,7 +5545,7 @@ var WebGPUPicker = class {
       size: 256,
       usage: COPY_DST | MAP_READ
     });
-    encoder.copyTextureToBuffer({
+    encoder2.copyTextureToBuffer({
       texture: this.target,
       origin: {
         x: pixelX,
@@ -3860,7 +5557,7 @@ var WebGPUPicker = class {
       bytesPerRow: 256,
       rowsPerImage: 1
     }, { width: 1, height: 1, depthOrArrayLayers: 1 });
-    this.device.queue.submit([encoder.finish()]);
+    this.device.queue.submit([encoder2.finish()]);
     let pixel;
     try {
       await readback.mapAsync(MAP_READ);
@@ -4214,6 +5911,12 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
   prepareBatchGeometry(geometry) {
     this.requireGeometryCache().pin(geometry);
   }
+  prepareGeometry(geometry, update) {
+    this.requireGeometryCache().pin(geometry, update);
+  }
+  releaseGeometry(geometry) {
+    this.geometryCache?.unpin(geometry);
+  }
   releaseBatchGeometry(geometry) {
     this.geometryCache?.unpin(geometry);
   }
@@ -4341,6 +6044,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
             color: colorToRgba(batch.material.color),
             useVertexColor: Boolean(batch.geometry.colors),
             useInstancing: true,
+            useLighting: batch.material.shading === "directional" || batch.material.shading === "water",
             pipeline: pagePipeline.triangle,
             useSelectionMask: selectionMaskEnabled,
             storagePage: page,
@@ -4368,6 +6072,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
           color: colorToRgba(batch.material.color),
           useVertexColor: Boolean(batch.geometry.colors),
           useInstancing: true,
+          useLighting: batch.material.shading === "directional" || batch.material.shading === "water",
           pipeline: this.pipeline.triangle,
           useSelectionMask: selectionMaskEnabled
         }, viewProjection.elements, batch.semanticIds);
@@ -4412,6 +6117,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
         color: colorToRgba(draw.batch.material.color),
         useVertexColor: Boolean(draw.batch.geometry.colors),
         useInstancing: false,
+        useLighting: draw.batch.material.shading === "directional" || draw.batch.material.shading === "water",
         pipeline: this.pipeline.triangle,
         useSelectionMask: selectionMaskEnabled
       }, matrix, draw.batch.semanticSelectionIds);
@@ -4459,6 +6165,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
         color: colorToRgba(renderable.mesh.material.color),
         useVertexColor: Boolean(renderable.mesh.geometry.colors),
         useInstancing: false,
+        useLighting: renderable.mesh.material.shading === "directional" || renderable.mesh.material.shading === "water",
         pipeline: this.pipeline.triangle,
         useSelectionMask: selectionMaskEnabled
       }, matrix, [renderable.mesh.selectionId]);
@@ -4527,26 +6234,26 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
       this.frameBindGroupKey = bindGroupKey;
     }
     const bindGroup = this.frameBindGroup;
-    const encodeDraws = (encoder2) => {
+    const encodeDraws = (encoder3) => {
       for (let index = 0; index < drawList.length; index += 1) {
         const draw = drawList[index];
-        encoder2.setPipeline(draw.pipeline);
+        encoder3.setPipeline(draw.pipeline);
         const drawBindGroup = draw.storagePage ? this.storageBindGroupFor(draw.storagePage, draw.visibilityEntry?.visibleBuffer) : bindGroup;
-        encoder2.setBindGroup(0, drawBindGroup, [
+        encoder3.setBindGroup(0, drawBindGroup, [
           index * WEBGPU_UNIFORM_STRIDE
         ]);
-        encoder2.setVertexBuffer(0, draw.geometry.vertexBuffer);
+        encoder3.setVertexBuffer(0, draw.geometry.vertexBuffer);
         if (draw.storagePage) {
-          encoder2.setVertexBuffer(1, draw.semanticBuffer);
+          encoder3.setVertexBuffer(1, draw.semanticBuffer);
         } else {
-          encoder2.setVertexBuffer(1, draw.instanceBuffer);
-          encoder2.setVertexBuffer(2, draw.semanticBuffer);
+          encoder3.setVertexBuffer(1, draw.instanceBuffer);
+          encoder3.setVertexBuffer(2, draw.semanticBuffer);
         }
-        encoder2.setIndexBuffer(draw.edge ? draw.geometry.edgeIndexBuffer : draw.geometry.triangleIndexBuffer, draw.geometry.indexFormat);
+        encoder3.setIndexBuffer(draw.edge ? draw.geometry.edgeIndexBuffer : draw.geometry.triangleIndexBuffer, draw.geometry.indexFormat);
         if (draw.visibilityEntry) {
-          encoder2.drawIndexedIndirect(draw.visibilityEntry.indirectBuffer, 0);
+          encoder3.drawIndexedIndirect(draw.visibilityEntry.indirectBuffer, 0);
         } else {
-          encoder2.drawIndexed(draw.edge ? draw.geometry.edgeCount : draw.geometry.triangleCount, draw.instanceCount, 0, 0, draw.storagePage?.firstInstance ?? 0);
+          encoder3.drawIndexed(draw.edge ? draw.geometry.edgeCount : draw.geometry.triangleCount, draw.instanceCount, 0, 0, draw.storagePage?.firstInstance ?? 0);
         }
       }
     };
@@ -4572,7 +6279,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
       }
     }
     const targetTexture = context.getCurrentTexture();
-    const encoder = this.device.createCommandEncoder();
+    const encoder2 = this.device.createCommandEncoder();
     if (this.gpuDrivenActive) {
       const encodedVisibility = /* @__PURE__ */ new Set();
       for (let index = 0; index < drawList.length; index += 1) {
@@ -4581,12 +6288,12 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
           continue;
         }
         encodedVisibility.add(draw.visibilityEntry);
-        this.visibilityEncoder.encode(encoder, draw.visibilityEntry, draw.storagePage, this.uniformBuffer, index * WEBGPU_UNIFORM_STRIDE);
+        this.visibilityEncoder.encode(encoder2, draw.visibilityEntry, draw.storagePage, this.uniformBuffer, index * WEBGPU_UNIFORM_STRIDE);
       }
     }
     const timestampProfiler = this.captureRequest || !this.timestampProfilingEnabled ? null : this.timestampProfiler;
     const timestampQuerySet = timestampProfiler?.querySetFor(frame.frameId);
-    const pass = encoder.beginRenderPass({
+    const pass = encoder2.beginRenderPass({
       colorAttachments: [{
         view: targetTexture.createView(),
         clearValue: {
@@ -4627,10 +6334,10 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
     this.frameStats.drawCalls += drawList.length;
     pass.end();
     if (timestampProfiler) {
-      timestampProfiler.resolveFrame(encoder, frame.frameId);
+      timestampProfiler.resolveFrame(encoder2, frame.frameId);
     }
     if (this.captureRequest) {
-      encoder.copyTextureToBuffer({ texture: targetTexture }, {
+      encoder2.copyTextureToBuffer({ texture: targetTexture }, {
         buffer: this.captureRequest.buffer,
         bytesPerRow: this.captureRequest.bytesPerRow,
         rowsPerImage: this.canvas.height
@@ -4641,7 +6348,7 @@ var WebGPURendererBackend = class _WebGPURendererBackend {
       });
       this.captureRequest = null;
     }
-    const commandBuffer = encoder.finish();
+    const commandBuffer = encoder2.finish();
     this.profiler.mark("encode");
     this.device.queue.submit([commandBuffer]);
     this.profiler.mark("submit");
@@ -5493,18 +7200,18 @@ var ICEInputRouter = class {
 function pickSceneNode(scene, camera, viewport, point) {
   const eye = camera.getPosition();
   const target = camera.getTarget();
-  const forward = normalize2([
+  const forward = normalize3([
     target.x - eye.x,
     target.y - eye.y,
     target.z - eye.z
   ]);
-  const right = normalize2(cross2(forward, [0, 1, 0]));
-  const up = normalize2(cross2(right, forward));
+  const right = normalize3(cross2(forward, [0, 1, 0]));
+  const up = normalize3(cross2(right, forward));
   const aspect = viewport.width / Math.max(viewport.height, 1);
   const tangent = Math.tan(camera.fov * Math.PI / 360);
   const ndcX = point.x / viewport.width * 2 - 1;
   const ndcY = 1 - point.y / viewport.height * 2;
-  const direction = normalize2([
+  const direction = normalize3([
     forward[0] + right[0] * ndcX * aspect * tangent + up[0] * ndcY * tangent,
     forward[1] + right[1] * ndcX * aspect * tangent + up[1] * ndcY * tangent,
     forward[2] + right[2] * ndcX * aspect * tangent + up[2] * ndcY * tangent
@@ -5537,7 +7244,7 @@ function pickSceneNode(scene, camera, viewport, point) {
   visit2(scene, true);
   return nearest;
 }
-var normalize2 = (value) => {
+var normalize3 = (value) => {
   const length = Math.hypot(...value);
   return length > 0 ? [value[0] / length, value[1] / length, value[2] / length] : [0, 0, 0];
 };
@@ -5847,6 +7554,7 @@ var ICE3 = class extends ICEEventDispatcher {
   generatedOverlayCanvas = false;
   scene = null;
   camera = null;
+  clipPlane = [0, 0, 0, 0];
   viewport = { x: 0, y: 0, width: 1, height: 1 };
   dpr = 1;
   frameId = 0;
@@ -5942,6 +7650,10 @@ var ICE3 = class extends ICEEventDispatcher {
           if (this.state === "destroyed")
             return;
           this.recordDiagnostic(error.code, error.message, "error");
+        },
+        onUploadReady: () => {
+          if (this.state === "running")
+            this.requestRender("upload-ready");
         }
       });
       window.addEventListener("resize", this.handleWindowResize);
@@ -5986,6 +7698,17 @@ var ICE3 = class extends ICEEventDispatcher {
     this.requestRender("background-color");
     return this;
   }
+  /**
+   * Section plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0`
+   * are discarded. `null` (or a zero plane) disables clipping.
+   */
+  setClipPlane(plane) {
+    this.assertActive();
+    this.clipPlane = plane ? [plane[0], plane[1], plane[2], plane[3]] : [0, 0, 0, 0];
+    this.backend.setClipPlane?.(this.clipPlane);
+    this.requestRender("clip-plane");
+    return this;
+  }
   prepareRenderBatchGeometry(geometry) {
     if (!this.backend.prepareBatchGeometry) {
       throw new ICEEngineError("ICE3_RENDER_BATCH_ADAPTER_UNAVAILABLE", "The active renderer cannot stage adaptive batch geometry");
@@ -5997,6 +7720,17 @@ var ICE3 = class extends ICEEventDispatcher {
     this.backend.releaseBatchGeometry?.(geometry);
     return this;
   }
+  prepareGeometry(geometry, update) {
+    if (!this.backend.prepareGeometry) {
+      throw new ICEEngineError("ICE3_RENDER_GEOMETRY_UNAVAILABLE", "The active renderer cannot stage geometry updates");
+    }
+    this.backend.prepareGeometry(geometry, update);
+    return this;
+  }
+  releaseGeometry(geometry) {
+    this.backend.releaseGeometry?.(geometry);
+    return this;
+  }
   addLayer(layer) {
     this.assertActive();
     if (this.layers.some((item) => item.id === layer.id)) {
@@ -6460,7 +8194,11 @@ var MAX_FRAME_DELTA_MS = 64;
 var SETTLE_EPSILON = 1e-5;
 var WHEEL_LINE_HEIGHT_PX = 16;
 var MAX_WHEEL_STEP_PX = 240;
-var MOVE_SPEED_PER_DISTANCE = 0.75;
+var ZOOM_DISTANCE_PER_HOME_PIXEL = 1e-3;
+var PAN_SPEED_PER_HOME_DISTANCE = 0.75;
+var MIN_KEY_TAP_MS = 16;
+var MIN_ZOOM_FRACTION = 5e-3;
+var ABSOLUTE_MIN_ZOOM_DISTANCE = 0.2;
 var NAVIGATION_KEYS = /* @__PURE__ */ new Set([
   "KeyW",
   "KeyA",
@@ -6478,6 +8216,8 @@ var ICEOrbitController = class {
   yaw;
   pitch;
   distance;
+  minDistance;
+  maxDistance;
   targetYaw;
   targetPitch;
   targetDistance;
@@ -6559,7 +8299,12 @@ var ICEOrbitController = class {
       return;
     }
     this.prepareMotion();
+    const alreadyPressed = this.pressedKeys.has(input.code);
     this.pressedKeys.add(input.code);
+    if (!alreadyPressed && !input.repeat) {
+      this.applyKeyboardMovement(MIN_KEY_TAP_MS);
+      this.applyPosition();
+    }
     this.engine.requestRender("camera-keyboard-movement");
   };
   onKeyUp = (event) => {
@@ -6603,7 +8348,9 @@ var ICEOrbitController = class {
     const offsetY = eye.y - target.y;
     const offsetZ = eye.z - target.z;
     this.target = target.toArray();
-    this.distance = Math.max(0.2, Math.hypot(offsetX, offsetY, offsetZ));
+    this.distance = Math.max(ABSOLUTE_MIN_ZOOM_DISTANCE, Math.hypot(offsetX, offsetY, offsetZ));
+    this.maxDistance = this.distance;
+    this.minDistance = Math.min(this.maxDistance, Math.max(ABSOLUTE_MIN_ZOOM_DISTANCE, this.maxDistance * MIN_ZOOM_FRACTION));
     this.yaw = Math.atan2(offsetX, offsetZ);
     this.pitch = Math.asin(clamp(offsetY / this.distance, -1, 1));
     this.targetYaw = this.yaw;
@@ -6623,7 +8370,7 @@ var ICEOrbitController = class {
     ];
     const radius = Math.max(0.1, Math.hypot(target.bounds.max[0] - target.bounds.min[0], target.bounds.max[1] - target.bounds.min[1], target.bounds.max[2] - target.bounds.min[2]) / 2);
     this.target = center;
-    this.targetDistance = radius / Math.sin(this.camera.fov * Math.PI / 360) * padding;
+    this.targetDistance = clamp(radius / Math.sin(this.camera.fov * Math.PI / 360) * padding, this.minDistance, this.maxDistance);
     if (options.animate === false) {
       this.distance = this.targetDistance;
       this.applyPosition();
@@ -6642,7 +8389,7 @@ var ICEOrbitController = class {
   zoomBy(delta) {
     this.assertActive();
     this.prepareMotion();
-    this.targetDistance = clamp(this.targetDistance * Math.exp(delta * 1e-3), 0.2, 100);
+    this.targetDistance = clamp(this.targetDistance + delta * this.maxDistance * ZOOM_DISTANCE_PER_HOME_PIXEL, this.minDistance, this.maxDistance);
     this.engine.requestRender("camera-zoom");
     return this;
   }
@@ -6688,7 +8435,7 @@ var ICEOrbitController = class {
     if (magnitude === 0) {
       return;
     }
-    const distance2 = this.distance * MOVE_SPEED_PER_DISTANCE * (deltaMs / 1e3) / magnitude;
+    const distance2 = this.maxDistance * PAN_SPEED_PER_HOME_DISTANCE * (deltaMs / 1e3) / magnitude;
     const sinYaw = Math.sin(this.yaw);
     const cosYaw = Math.cos(this.yaw);
     const sinPitch = Math.sin(this.pitch);
@@ -6754,7 +8501,14 @@ function buildAssetScene(snapshot) {
   }));
   const materials = snapshot.materials.map((material) => new ICEBasicMaterial({
     color: material.baseColor,
-    ...material.edgeColor ? { edgeColor: material.edgeColor } : {}
+    ...material.edgeColor ? { edgeColor: material.edgeColor } : {},
+    ...material.shading ? { shading: material.shading } : {},
+    ...material.map ? { map: material.map } : {},
+    ...material.normalMap ? { normalMap: material.normalMap } : {},
+    ...material.ormMap ? { ormMap: material.ormMap } : {},
+    ...material.metallic !== void 0 ? { metallic: material.metallic } : {},
+    ...material.roughness !== void 0 ? { roughness: material.roughness } : {},
+    ...material.emissive ? { emissive: material.emissive } : {}
   }));
   const meshesByNode = /* @__PURE__ */ new Map();
   for (const mesh of snapshot.meshes) {
@@ -6829,8 +8583,123 @@ function buildAssetScene(snapshot) {
     stats: snapshot.stats
   };
 }
+function buildPreviewPacketScene(packet, previousGeometries = /* @__PURE__ */ new Map()) {
+  const geometries = /* @__PURE__ */ new Map();
+  const geometryUpdates = /* @__PURE__ */ new Map();
+  for (const source of packet.geometries) {
+    const previous = previousGeometries.get(source.geometryId);
+    if (previous && previous.identity.topologyDigest === source.topologyDigest && previous.identity.attributeDigest === source.attributeDigest) {
+      geometries.set(source.geometryId, previous);
+      continue;
+    }
+    const identity = Object.freeze({
+      geometryId: source.geometryId,
+      topologyDigest: source.topologyDigest,
+      attributeDigest: source.attributeDigest
+    });
+    const geometry = new ICEIndexedGeometry({
+      id: source.residentGeometryId ?? source.geometryId,
+      identity,
+      positions: source.positions,
+      indices: source.indices
+    });
+    geometries.set(source.geometryId, geometry);
+    const attributeRanges = source.ranges.filter((range) => range.usage === "vertex_attributes");
+    const attributeStart = Math.min(...attributeRanges.map((range) => range.byteOffset));
+    geometryUpdates.set(source.geometryId, Object.freeze({
+      positionRanges: Object.freeze(attributeRanges.map((range) => Object.freeze({
+        byteOffset: range.byteOffset - attributeStart,
+        byteLength: range.byteLength
+      })))
+    }));
+  }
+  const materials = new Map(packet.materials.map((material) => [
+    material.materialId,
+    new ICEBasicMaterial({
+      color: colorHex(material.baseColor)
+    })
+  ]));
+  const defaultMaterial = new ICEBasicMaterial({
+    color: "#9aa6b2"
+  });
+  const scene = new ICEScene({ id: `packet:${packet.revision}:scene` });
+  const nodes = /* @__PURE__ */ new Map();
+  for (const source of packet.nodes) {
+    const geometry = source.geometryId ? geometries.get(source.geometryId) : void 0;
+    const material = source.materialId ? materials.get(source.materialId) ?? defaultMaterial : defaultMaterial;
+    const options = {
+      id: source.nodeId,
+      displayName: source.name,
+      selectionId: source.nodeId,
+      matrix: source.matrix
+    };
+    const node = geometry ? new ICEMesh({
+      ...options,
+      geometry,
+      material
+    }) : new ICENode(options);
+    node.visible = source.visible;
+    nodes.set(source.nodeId, node);
+  }
+  for (const source of packet.nodes) {
+    const node = nodes.get(source.nodeId);
+    const parent = source.parentId ? nodes.get(source.parentId) : void 0;
+    if (source.parentId && !parent) {
+      throw new Error(`ICE3_PREVIEW_PACKET_INVALID: parent node ${source.parentId} is missing`);
+    }
+    (parent ?? scene).addChild(node);
+  }
+  return {
+    scene,
+    geometries,
+    geometryUpdates
+  };
+}
+function colorHex(color) {
+  const channel = (value) => Math.round(Math.max(0, Math.min(1, value)) * 255).toString(16).padStart(2, "0");
+  return `#${channel(color[0])}${channel(color[1])}${channel(color[2])}`;
+}
 
 // packages/assets/dist/ICEProfileValidator.js
+function validateTextures(json) {
+  const images = records(json.images);
+  const textures = records(json.textures);
+  const samplers = records(json.samplers);
+  for (const image of images) {
+    const uri = image.uri;
+    if (typeof uri !== "string" || !uri || uri.startsWith("/") || uri.includes("..") || uri.includes("://") || image.bufferView !== void 0) {
+      throw assetError("ICE3_ASSET_UNSUPPORTED_FEATURE", "images must reference a relative file path");
+    }
+  }
+  for (const texture of textures) {
+    const source = Number(texture.source);
+    if (!Number.isInteger(source) || source < 0 || source >= images.length) {
+      throw assetError("ICE3_ASSET_INVALID_GLB", "texture source is out of range");
+    }
+    if (texture.sampler !== void 0) {
+      const sampler = Number(texture.sampler);
+      if (!Number.isInteger(sampler) || sampler < 0 || sampler >= samplers.length) {
+        throw assetError("ICE3_ASSET_INVALID_GLB", "texture sampler is out of range");
+      }
+    }
+  }
+  for (const material of records(json.materials)) {
+    const slots = [
+      ["baseColorTexture", record(record(material.pbrMetallicRoughness)?.baseColorTexture)],
+      ["normalTexture", record(material.normalTexture)],
+      ["metallicRoughnessTexture", record(record(material.pbrMetallicRoughness)?.metallicRoughnessTexture)],
+      ["occlusionTexture", record(material.occlusionTexture)]
+    ];
+    for (const [slot, reference] of slots) {
+      if (!reference)
+        continue;
+      const index = Number(reference.index);
+      if (!Number.isInteger(index) || index < 0 || index >= textures.length) {
+        throw assetError("ICE3_ASSET_INVALID_GLB", `${slot} index is out of range`);
+      }
+    }
+  }
+}
 function validatePreparedProfile(json, binary) {
   const asset = record(json.asset);
   const profile = record(record(asset?.extras)?.ice3);
@@ -6858,15 +8727,13 @@ function validatePreparedProfile(json, binary) {
     "animations",
     "skins",
     "cameras",
-    "textures",
-    "images",
-    "samplers",
     "lights"
   ]) {
     if (Array.isArray(json[field]) && json[field].length > 0) {
       throw assetError("ICE3_ASSET_UNSUPPORTED_FEATURE", `${field} are unsupported by the M1 profile`);
     }
   }
+  validateTextures(json);
   if (records(json.scenes).length !== 1 || json.scene !== 0 || records(json.buffers).length !== 1 || records(json.buffers)[0]?.uri !== void 0 || Number(records(json.buffers)[0]?.byteLength) > binary.byteLength) {
     throw assetError("ICE3_ASSET_INVALID_GLB", "profile container fields are invalid");
   }
@@ -6948,9 +8815,9 @@ function validatePreparedStats(json, profile) {
   let primitiveCount = 0;
   let triangleCount = 0;
   let edgeSegmentCount = 0;
-  const selectionNodes = /* @__PURE__ */ new Set();
+  const selectionIds = /* @__PURE__ */ new Set();
   const referencedMeshes = /* @__PURE__ */ new Set();
-  for (const [nodeIndex, node] of nodes.entries()) {
+  for (const node of nodes) {
     if (node.mesh === void 0)
       continue;
     const mesh = meshes[Number(node.mesh)];
@@ -6960,7 +8827,10 @@ function validatePreparedStats(json, profile) {
     for (const primitive of records(mesh.primitives)) {
       const mode = Number(primitive.mode ?? 4);
       if (mode === 4) {
-        selectionNodes.add(nodeIndex);
+        const nodeProfile = record(record(node.extras)?.ice3);
+        const selectionId = nodeProfile?.selectionId ?? nodeProfile?.id;
+        if (typeof selectionId === "string")
+          selectionIds.add(selectionId);
       }
     }
   }
@@ -6986,7 +8856,7 @@ function validatePreparedStats(json, profile) {
     triangleCount,
     edgeSegmentCount,
     materialCount: records(json.materials).length,
-    selectionGroupCount: Array.isArray(batchingSelectionIds) ? new Set(batchingSelectionIds).size : selectionNodes.size
+    selectionGroupCount: Array.isArray(batchingSelectionIds) ? new Set(batchingSelectionIds).size : selectionIds.size
   };
   for (const [key, value] of Object.entries(expected)) {
     if (stats?.[key] !== value) {
@@ -7021,13 +8891,15 @@ function assetError(code, message) {
 }
 
 // packages/assets/dist/ICEGLBReader.js
-function readPreparedGLB(bytes) {
+function readPreparedGLB(bytes, options = {}) {
   const { json, binary, profile } = parseGLB(bytes);
   const accessors = records(json.accessors);
   const views = records(json.bufferViews);
   const sourceNodes = records(json.nodes);
   const sourceMeshes = records(json.meshes);
   const sourceMaterials = records(json.materials);
+  const sourceTextures = records(json.textures);
+  const sourceImages = records(json.images);
   const activeScene = records(json.scenes)[Number(json.scene ?? 0)];
   const sceneRoots = integers(activeScene?.nodes);
   const parents = new Array(sourceNodes.length).fill(null);
@@ -7076,7 +8948,7 @@ function readPreparedGLB(bytes) {
   const geometries = [];
   const materials = [];
   const meshes = [];
-  const selectionNodes = /* @__PURE__ */ new Set();
+  const selectionIds = /* @__PURE__ */ new Set();
   let primitiveCount = 0;
   let triangleCount = 0;
   let edgeSegmentCount = 0;
@@ -7108,11 +8980,20 @@ function readPreparedGLB(bytes) {
       edgeSegmentCount += (edgeIndices?.length ?? 0) / 2;
       const baseMaterial = sourceMaterials[Number(primitive.material)];
       const edgeMaterial = edgePrimitive ? sourceMaterials[Number(edgePrimitive.material)] : void 0;
+      const shading = record(record(baseMaterial?.extras)?.ice3)?.shading;
       const materialIndex = materials.length;
+      const map = materialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
+      const normalMap = normalMaterialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
+      const ormMap = ormMaterialMap(baseMaterial, sourceTextures, sourceImages, options.baseUrl);
       materials.push({
         id: `${meshId}/material/${primitiveIndex}`,
         baseColor: materialColor(baseMaterial),
-        ...edgeMaterial ? { edgeColor: materialColor(edgeMaterial) } : {}
+        ...edgeMaterial ? { edgeColor: materialColor(edgeMaterial) } : {},
+        ...shading === "directional" || shading === "water" ? { shading } : {},
+        ...map ? { map } : {},
+        ...normalMap ? { normalMap } : {},
+        ...ormMap ? { ormMap } : {},
+        ...surfaceFactors(baseMaterial)
       });
       const bounds = boundsFromAccessor(accessors[positionIndex]);
       const geometryIndex = geometries.length;
@@ -7126,7 +9007,7 @@ function readPreparedGLB(bytes) {
         bounds
       });
       for (const entry of nodesForMesh) {
-        selectionNodes.add(entry.index);
+        selectionIds.add(nodes[entry.index].selectionId);
         meshes.push({
           id: `${meshId}/primitive/${primitiveIndex}/${entry.index}`,
           node: entry.index,
@@ -7144,7 +9025,7 @@ function readPreparedGLB(bytes) {
     triangleCount,
     edgeSegmentCount,
     materialCount: sourceMaterials.length,
-    selectionGroupCount: selectionNodes.size
+    selectionGroupCount: batching ? new Set(batching.semanticSelectionIds).size : selectionIds.size
   };
   const contract = preparedContract(profile);
   return {
@@ -7168,7 +9049,7 @@ function readBatchingMetadata(profile, sourceNodes, sourceMeshes, sourceMaterial
   }
   const semanticIds = stringArray(raw.semanticIds, "semanticIds");
   const semanticNodeIds = stringArray(raw.semanticNodeIds, "semanticNodeIds");
-  const semanticSelectionIds = stringArray(raw.semanticSelectionIds, "semanticSelectionIds");
+  const semanticSelectionIds = stringArray(raw.semanticSelectionIds, "semanticSelectionIds", false);
   if (semanticIds.length === 0 || semanticNodeIds.length !== semanticIds.length || semanticSelectionIds.length !== semanticIds.length) {
     throw assetError2("ICE3_ASSET_BATCH_INVALID", "semantic arrays are inconsistent");
   }
@@ -7235,8 +9116,8 @@ function readBatchingMetadata(profile, sourceNodes, sourceMeshes, sourceMaterial
     batches
   };
 }
-function stringArray(value, field) {
-  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim()) || new Set(value).size !== value.length) {
+function stringArray(value, field, unique = true) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim()) || unique && new Set(value).size !== value.length) {
     throw assetError2("ICE3_ASSET_BATCH_INVALID", `${field} is invalid`);
   }
   return value;
@@ -7422,13 +9303,102 @@ function boundsFromProfile(value) {
     max: [Number(max[0]), Number(max[1]), Number(max[2])]
   };
 }
+function materialMap(material, textures, images, baseUrl) {
+  const reference = record(record(material?.pbrMetallicRoughness)?.baseColorTexture);
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const transform = record(record(reference.extensions)?.KHR_texture_transform);
+  const scale = numbers(transform?.scale, 2);
+  const su = scale?.[0];
+  const sv = scale?.[1];
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...typeof su === "number" && typeof sv === "number" && su > 0 && sv > 0 ? { scale: [su, sv] } : {}
+  };
+}
+function surfaceFactors(material) {
+  const pbr = record(material?.pbrMetallicRoughness);
+  const metallic = unitOrUndefined(pbr?.metallicFactor);
+  const roughness = unitOrUndefined(pbr?.roughnessFactor);
+  const emissive = numbers(material?.emissiveFactor, 3);
+  return {
+    ...metallic !== void 0 ? { metallic } : {},
+    ...roughness !== void 0 ? { roughness } : {},
+    ...emissive && emissive.some((value) => value > 0) ? { emissive: [emissive[0], emissive[1], emissive[2]] } : {}
+  };
+}
+function unitOrUndefined(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed))
+    return void 0;
+  return Math.min(1, Math.max(0, parsed));
+}
+function normalMaterialMap(material, textures, images, baseUrl) {
+  const reference = record(material?.normalTexture);
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const strength = Number(reference.scale);
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...Number.isFinite(strength) && strength >= 0 ? { strength } : {}
+  };
+}
+function ormMaterialMap(material, textures, images, baseUrl) {
+  const metallicRoughness = textureReference(record(record(material?.pbrMetallicRoughness)?.metallicRoughnessTexture), textures, images, baseUrl);
+  const occlusion = textureReference(record(material?.occlusionTexture), textures, images, baseUrl);
+  if (!metallicRoughness && !occlusion)
+    return void 0;
+  const url = metallicRoughness?.url ?? occlusion.url;
+  const scale = metallicRoughness?.scale ?? occlusion?.scale;
+  return {
+    url,
+    ...scale ? { scale } : {},
+    occlusion: occlusion?.url === url,
+    metallicRoughness: metallicRoughness !== void 0
+  };
+}
+function textureReference(reference, textures, images, baseUrl) {
+  if (!reference)
+    return void 0;
+  const texture = textures[Number(reference.index)];
+  const uri = record(images[Number(record(texture)?.source)])?.uri;
+  if (typeof uri !== "string" || uri.length === 0)
+    return void 0;
+  const transform = record(record(reference.extensions)?.KHR_texture_transform);
+  const scale = numbers(transform?.scale, 2);
+  const su = scale?.[0];
+  const sv = scale?.[1];
+  return {
+    url: resolveTextureUrl(uri, baseUrl),
+    ...typeof su === "number" && typeof sv === "number" && su > 0 && sv > 0 ? { scale: [su, sv] } : {}
+  };
+}
+function resolveTextureUrl(uri, baseUrl) {
+  if (!baseUrl)
+    return uri;
+  try {
+    return new URL(uri, baseUrl).href;
+  } catch {
+    return uri;
+  }
+}
 function materialColor(material) {
   if (!material)
     return "#808080";
   const color = record(material.pbrMetallicRoughness)?.baseColorFactor;
   if (!Array.isArray(color) || color.length < 3)
     return "#808080";
-  return `#${color.slice(0, 3).map((value) => Math.round(Math.min(1, Math.max(0, Number(value))) * 255).toString(16).padStart(2, "0")).join("")}`;
+  const alpha = color.length >= 4 ? Number(color[3]) : 1;
+  const channels = color.slice(0, alpha < 1 ? 4 : 3).map((value) => Math.round(Math.min(1, Math.max(0, Number(value))) * 255).toString(16).padStart(2, "0"));
+  return `#${channels.join("")}`;
 }
 function integers(value) {
   return Array.isArray(value) ? value.filter((entry) => Number.isInteger(entry)) : [];
@@ -7443,6 +9413,494 @@ function assetError2(code, message) {
   return new Error(`${code}: ${message}`);
 }
 
+// packages/assets/dist/ICEPreviewGeometryPacket.js
+var MAGIC = "ICE3PGP1";
+var HEADER_BYTES = 120;
+var MANIFEST_LENGTH_OFFSET = 40;
+var BINARY_LENGTH_OFFSET = 48;
+var MANIFEST_DIGEST_OFFSET = 56;
+var CONTENT_DIGEST_OFFSET = 88;
+var MAX_PACKET_BYTES = 256 * 1024 * 1024;
+var MAX_NODES = 1e6;
+var MAX_GEOMETRIES = 25e4;
+var MAX_RANGES = 64;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+function parsePreviewGeometryPacket(input) {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  if (bytes.byteLength < HEADER_BYTES || bytes.byteLength > MAX_PACKET_BYTES) {
+    throw new RangeError("ICE3 preview packet size is invalid");
+  }
+  if (decoder.decode(bytes.subarray(0, 8)) !== MAGIC) {
+    throw new TypeError("ICE3 preview packet magic is invalid");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const schemaVersion = view.getUint16(8, true);
+  const transportVersion = view.getUint16(10, true);
+  const headerBytes = view.getUint32(12, true);
+  if (schemaVersion !== 1 || transportVersion !== 1 || headerBytes !== HEADER_BYTES) {
+    throw new TypeError("ICE3 preview packet version is unsupported");
+  }
+  const manifestLength = readSafeU64(view, MANIFEST_LENGTH_OFFSET);
+  const binaryLength = readSafeU64(view, BINARY_LENGTH_OFFSET);
+  if (manifestLength === 0 || manifestLength % 8 !== 0 || HEADER_BYTES + manifestLength + binaryLength !== bytes.byteLength) {
+    throw new RangeError("ICE3 preview packet lengths are invalid");
+  }
+  const manifestStart = HEADER_BYTES;
+  const manifestEnd = manifestStart + manifestLength;
+  const manifestBytes = bytes.subarray(manifestStart, manifestEnd);
+  const binary = bytes.subarray(manifestEnd);
+  const expectedManifestDigest = bytes.subarray(MANIFEST_DIGEST_OFFSET, MANIFEST_DIGEST_OFFSET + 32);
+  if (!equalBytes(sha256(manifestBytes), expectedManifestDigest)) {
+    throw new TypeError("ICE3 preview packet manifest digest is invalid");
+  }
+  const contentHash = sha256(concatBytes(manifestBytes, binary));
+  const expectedContentDigest = bytes.subarray(CONTENT_DIGEST_OFFSET, CONTENT_DIGEST_OFFSET + 32);
+  if (!equalBytes(contentHash, expectedContentDigest)) {
+    throw new TypeError("ICE3 preview packet content digest is invalid");
+  }
+  let candidate;
+  try {
+    candidate = JSON.parse(decoder.decode(manifestBytes));
+  } catch {
+    throw new TypeError("ICE3 preview packet manifest is invalid");
+  }
+  const manifest = validateManifest(candidate, binary.byteLength);
+  return {
+    ...manifest,
+    geometries: manifest.geometries.map((geometry) => decodeGeometry(geometry, binary)),
+    binary
+  };
+}
+function applyPreviewGeometryDelta(base, delta) {
+  if (delta.parentRevision !== base.revision) {
+    throw new RangeError(`ICE3 preview packet parent revision ${delta.parentRevision ?? "missing"} does not match ${base.revision}`);
+  }
+  const nodes = mergeById(base.nodes, delta.nodes, delta.removedNodeIds, (node) => node.nodeId);
+  const geometries = mergeGeometries(base.geometries, delta, delta.removedGeometryIds);
+  const materials = mergeById(base.materials, delta.materials, [], (material) => material.materialId);
+  return {
+    schemaVersion: delta.schemaVersion,
+    transportVersion: delta.transportVersion,
+    revision: delta.revision,
+    parentRevision: delta.parentRevision,
+    sourceDigest: delta.sourceDigest,
+    backend: delta.backend,
+    residencyMode: delta.residencyMode,
+    nodes,
+    geometries,
+    materials,
+    removedNodeIds: [],
+    removedGeometryIds: [],
+    binary: delta.binary
+  };
+}
+function mergeGeometries(baseGeometries, delta, removedGeometryIds) {
+  const removed = new Set(removedGeometryIds);
+  const updates = new Map(delta.geometries.map((geometry) => [geometry.geometryId, geometry]));
+  const output = [];
+  for (const base of baseGeometries) {
+    if (removed.has(base.geometryId)) {
+      continue;
+    }
+    const update = updates.get(base.geometryId);
+    output.push(update ? mergeGeometry(base, update) : base);
+    updates.delete(base.geometryId);
+  }
+  output.push(...updates.values());
+  return Object.freeze(output);
+}
+function mergeGeometry(base, update) {
+  if (base === update) {
+    return base;
+  }
+  return freezeGeometry(update, base.attributeDigest === update.attributeDigest ? base.positions : update.positions, base.topologyDigest === update.topologyDigest ? base.indices : update.indices);
+}
+function validateManifest(value, binaryLength) {
+  if (!isRecord(value)) {
+    throw invalidManifest();
+  }
+  const nodes = readArray(value.nodes, MAX_NODES).map(readNode);
+  const geometries = readArray(value.geometries, MAX_GEOMETRIES).map(readGeometryRecord);
+  const materials = readArray(value.materials, MAX_GEOMETRIES).map(readMaterial);
+  const removedNodeIds = readStringArray(value.removedNodeIds, MAX_NODES);
+  const removedGeometryIds = readStringArray(value.removedGeometryIds, MAX_GEOMETRIES);
+  const manifest = {
+    schemaVersion: readVersion(value.schemaVersion, 1),
+    transportVersion: readVersion(value.transportVersion, 1),
+    revision: readSafeInteger(value.revision, 0, Number.MAX_SAFE_INTEGER),
+    parentRevision: value.parentRevision === null ? null : readSafeInteger(value.parentRevision, 0, Number.MAX_SAFE_INTEGER),
+    sourceDigest: readDigest(value.sourceDigest),
+    backend: readEnum(value.backend, ["cpu", "gpu"]),
+    residencyMode: readEnum(value.residencyMode, ["cpu", "cold", "warm", "resident", "snapshot"]),
+    nodes,
+    geometries,
+    materials,
+    removedNodeIds,
+    removedGeometryIds
+  };
+  if (manifest.parentRevision !== null && manifest.parentRevision >= manifest.revision) {
+    throw invalidManifest();
+  }
+  ensureUnique(nodes, (node) => node.nodeId);
+  ensureUnique(geometries, (geometry) => geometry.geometryId);
+  ensureUnique(materials, (material) => material.materialId);
+  for (const geometry of geometries) {
+    for (const range of geometry.ranges) {
+      if (range.byteOffset % 4 !== 0 || range.byteLength === 0 || range.byteOffset + range.byteLength > binaryLength) {
+        throw invalidManifest();
+      }
+    }
+  }
+  return manifest;
+}
+function readNode(value, index) {
+  if (!isRecord(value)) {
+    throw new TypeError(`ICE3 preview node ${index} is invalid`);
+  }
+  const matrix = readArray(value.matrix, 16);
+  if (matrix.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+    throw new TypeError(`ICE3 preview node ${index} matrix is invalid`);
+  }
+  return {
+    nodeId: readNonEmptyString(value.nodeId),
+    parentId: readNullableString(value.parentId),
+    name: readString(value.name),
+    matrix: Object.freeze(matrix),
+    materialId: readNullableString(value.materialId),
+    geometryId: readNullableString(value.geometryId),
+    visible: readBoolean(value.visible)
+  };
+}
+function readGeometryRecord(value, index) {
+  if (!isRecord(value)) {
+    throw new TypeError(`ICE3 preview geometry ${index} is invalid`);
+  }
+  const indexWidth = readSafeInteger(value.indexWidth, 1, 8);
+  if (indexWidth !== 2 && indexWidth !== 4) {
+    throw new TypeError(`ICE3 preview geometry ${index} index width is invalid`);
+  }
+  const ranges = readArray(value.ranges, MAX_RANGES).map(readRange);
+  return {
+    geometryId: readNonEmptyString(value.geometryId),
+    residentGeometryId: readNullableString(value.residentGeometryId),
+    topologyDigest: readDigest(value.topologyDigest),
+    attributeDigest: readDigest(value.attributeDigest),
+    vertexCount: readSafeInteger(value.vertexCount, 1, 1e8),
+    indexCount: readSafeInteger(value.indexCount, 0, 3e8),
+    indexWidth,
+    ranges: Object.freeze(ranges)
+  };
+}
+function readRange(value, index) {
+  if (!isRecord(value)) {
+    throw new TypeError(`ICE3 preview range ${index} is invalid`);
+  }
+  return {
+    byteOffset: readSafeInteger(value.byteOffset, 0, MAX_PACKET_BYTES),
+    byteLength: readSafeInteger(value.byteLength, 1, MAX_PACKET_BYTES),
+    usage: readEnum(value.usage, ["vertex_attributes", "indices"])
+  };
+}
+function readMaterial(value, index) {
+  if (!isRecord(value)) {
+    throw new TypeError(`ICE3 preview material ${index} is invalid`);
+  }
+  const baseColor = readFiniteArray(value.baseColor, 4);
+  return {
+    materialId: readNonEmptyString(value.materialId),
+    baseColor: Object.freeze(baseColor),
+    metallic: readFiniteNumber(value.metallic),
+    roughness: readFiniteNumber(value.roughness),
+    opacity: readFiniteNumber(value.opacity)
+  };
+}
+function decodeGeometry(geometry, binary) {
+  const attributes = geometry.ranges.find((range) => range.usage === "vertex_attributes");
+  const topology = geometry.ranges.find((range) => range.usage === "indices");
+  if (!attributes && !topology) {
+    return freezeGeometry(encodeIdentity(geometry), new Float32Array(), new Uint32Array());
+  }
+  const positions = attributes ? decodePositions(attributes, geometry.vertexCount, binary) : new Float32Array(geometry.vertexCount * 3);
+  const indices = topology ? decodeIndices(topology, geometry.indexCount, geometry.indexWidth, binary) : new Uint32Array();
+  return freezeGeometry(encodeIdentity(geometry), positions, indices);
+}
+function decodePositions(range, vertexCount, binary) {
+  const bytesPerVertex = range.byteLength / vertexCount;
+  const components = bytesPerVertex / 4;
+  if (!Number.isInteger(components) || components < 3) {
+    throw new TypeError("ICE3 preview position range has an invalid stride");
+  }
+  const source = new Float32Array(binary.buffer, binary.byteOffset + range.byteOffset, range.byteLength / 4);
+  if (components === 3) {
+    return source;
+  }
+  const positions = new Float32Array(vertexCount * 3);
+  for (let vertex = 0; vertex < vertexCount; vertex += 1) {
+    const sourceOffset = vertex * components;
+    positions[vertex * 3] = source[sourceOffset];
+    positions[vertex * 3 + 1] = source[sourceOffset + 1];
+    positions[vertex * 3 + 2] = source[sourceOffset + 2];
+  }
+  return positions;
+}
+function decodeIndices(range, indexCount, indexWidth, binary) {
+  if (range.byteLength !== indexCount * indexWidth) {
+    throw new TypeError("ICE3 preview index range has an invalid length");
+  }
+  const offset = binary.byteOffset + range.byteOffset;
+  return indexWidth === 2 ? new Uint16Array(binary.buffer, offset, indexCount) : new Uint32Array(binary.buffer, offset, indexCount);
+}
+function freezeGeometry(identity, positions, indices) {
+  return Object.freeze({
+    ...identity,
+    positions,
+    indices
+  });
+}
+function encodeIdentity(geometry) {
+  return geometry;
+}
+function mergeById(base, updates, removed, id) {
+  const removedIds = new Set(removed);
+  const updateMap = new Map(updates.map((value) => [id(value), value]));
+  const output = base.filter((value) => !removedIds.has(id(value))).map((value) => updateMap.get(id(value)) ?? value);
+  const baseIds = new Set(base.map(id));
+  for (const value of updates) {
+    if (!baseIds.has(id(value))) {
+      output.push(value);
+    }
+  }
+  return Object.freeze(output);
+}
+function readArray(value, maximum) {
+  if (!Array.isArray(value) || value.length > maximum) {
+    throw invalidManifest();
+  }
+  return value;
+}
+function readStringArray(value, maximum) {
+  return Object.freeze(readArray(value, maximum).map(readString));
+}
+function readFiniteArray(value, length) {
+  const values = readArray(value, length);
+  if (values.length !== length || values.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+    throw invalidManifest();
+  }
+  return values;
+}
+function readVersion(value, expected) {
+  if (value !== expected) {
+    throw new TypeError("ICE3 preview packet version is unsupported");
+  }
+  return expected;
+}
+function readSafeInteger(value, minimum, maximum) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw invalidManifest();
+  }
+  return value;
+}
+function readFiniteNumber(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw invalidManifest();
+  }
+  return value;
+}
+function readBoolean(value) {
+  if (typeof value !== "boolean") {
+    throw invalidManifest();
+  }
+  return value;
+}
+function readString(value) {
+  if (typeof value !== "string") {
+    throw invalidManifest();
+  }
+  return value;
+}
+function readNonEmptyString(value) {
+  const result = readString(value);
+  if (!result.trim()) {
+    throw invalidManifest();
+  }
+  return result;
+}
+function readNullableString(value) {
+  return value === null ? null : readString(value);
+}
+function readDigest(value) {
+  const digest = readString(value);
+  if (!/^[0-9a-fA-F]{64}$/.test(digest)) {
+    throw invalidManifest();
+  }
+  return digest.toLowerCase();
+}
+function readEnum(value, allowed) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw invalidManifest();
+  }
+  return value;
+}
+function ensureUnique(values, id) {
+  if (new Set(values.map(id)).size !== values.length) {
+    throw invalidManifest();
+  }
+}
+function invalidManifest() {
+  return new TypeError("ICE3 preview packet manifest is invalid");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readSafeU64(view, offset) {
+  const value = view.getBigUint64(offset, true);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("ICE3 preview packet length exceeds safe integer range");
+  }
+  return Number(value);
+}
+function concatBytes(left, right) {
+  const output = new Uint8Array(left.length + right.length);
+  output.set(left);
+  output.set(right, left.length);
+  return output;
+}
+function equalBytes(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+var SHA256_CONSTANTS = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256(input) {
+  const bitLength = input.length * 8;
+  const paddedLength = Math.ceil((input.length + 9) / 64) * 64;
+  const data = new Uint8Array(paddedLength);
+  data.set(input);
+  data[input.length] = 128;
+  const view = new DataView(data.buffer);
+  view.setUint32(paddedLength - 8, Math.floor(bitLength / 4294967296));
+  view.setUint32(paddedLength - 4, bitLength >>> 0);
+  const hash = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const words = new Uint32Array(64);
+  for (let offset = 0; offset < data.length; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      words[index] = view.getUint32(offset + index * 4);
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const s0 = rotateRight(words[index - 15], 7) ^ rotateRight(words[index - 15], 18) ^ words[index - 15] >>> 3;
+      const s1 = rotateRight(words[index - 2], 17) ^ rotateRight(words[index - 2], 19) ^ words[index - 2] >>> 10;
+      words[index] = words[index - 16] + s0 + words[index - 7] + s1 >>> 0;
+    }
+    let [a, b, c, d, e, f, g, h] = hash;
+    for (let index = 0; index < 64; index += 1) {
+      const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choice = e & f ^ ~e & g;
+      const temp1 = h + sum1 + choice + SHA256_CONSTANTS[index] + words[index] >>> 0;
+      const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = a & b ^ a & c ^ b & c;
+      const temp2 = sum0 + majority >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    hash[0] = hash[0] + a >>> 0;
+    hash[1] = hash[1] + b >>> 0;
+    hash[2] = hash[2] + c >>> 0;
+    hash[3] = hash[3] + d >>> 0;
+    hash[4] = hash[4] + e >>> 0;
+    hash[5] = hash[5] + f >>> 0;
+    hash[6] = hash[6] + g >>> 0;
+    hash[7] = hash[7] + h >>> 0;
+  }
+  const output = new Uint8Array(32);
+  const outputView = new DataView(output.buffer);
+  for (let index = 0; index < hash.length; index += 1) {
+    outputView.setUint32(index * 4, hash[index], false);
+  }
+  return output;
+}
+function rotateRight(value, bits) {
+  return value >>> bits | value << 32 - bits;
+}
+
 // packages/assets/dist/ICETilesetReader.js
 var IDENTITY = [
   1,
@@ -7715,7 +10173,11 @@ function parseTransform(value) {
   return matrix;
 }
 function assertContains(parent, child, id) {
-  if ([0, 1, 2].some((axis) => child.min[axis] < parent.min[axis] - EPSILON || child.max[axis] > parent.max[axis] + EPSILON)) {
+  if ([0, 1, 2].some((axis) => {
+    const scale = Math.max(1, Math.abs(parent.min[axis]), Math.abs(parent.max[axis]), Math.abs(child.min[axis]), Math.abs(child.max[axis]));
+    const tolerance = EPSILON * scale;
+    return child.min[axis] < parent.min[axis] - tolerance || child.max[axis] > parent.max[axis] + tolerance;
+  })) {
     throw invalid(`child bounds escape parent tile ${id}`);
   }
 }
@@ -7828,7 +10290,7 @@ var ICEAssetLoader = class {
       throw new Error(`ICE3_ASSET_FETCH_FAILED: HTTP ${response.status}`);
     }
     const bytes = await response.arrayBuffer();
-    const snapshot = readPreparedGLB(bytes);
+    const snapshot = readPreparedGLB(bytes, { baseUrl: url });
     return { bytes, snapshot };
   }
 };
@@ -8618,7 +11080,7 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
   adaptivePlanningSignature = "";
   renderBatchingMode;
   visibleCoverageIds = /* @__PURE__ */ new Set();
-  constructor(engine, snapshot, camera, scheduler, fetch, maxConcurrentTiles, maxCommitsPerFrame, maxScreenSpaceErrorPixels, lodSettleDelayMs, renderBatching, callerSignal) {
+  constructor(engine, snapshot, camera, scheduler, fetch2, maxConcurrentTiles, maxCommitsPerFrame, maxScreenSpaceErrorPixels, lodSettleDelayMs, renderBatching, callerSignal) {
     super();
     this.engine = engine;
     this.snapshot = snapshot;
@@ -8649,7 +11111,7 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
       });
     }
     this.assetLoader = new ICEAssetLoader(engine, {
-      fetch: (input, init) => fetch(input, {
+      fetch: (input, init) => fetch2(input, {
         ...init ?? {},
         signal: this.abortController.signal
       })
@@ -9212,12 +11674,6 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
       this.assetLoader.clear(uri);
     this.states.set(tileId, "evicted");
     this.emit("TILESET_TILE_UNLOADED", tileId);
-    const remainingIds = /* @__PURE__ */ new Set();
-    collectNodeAndSelectionIDs(this.scene, remainingIds);
-    const selection = this.engine.getSelection();
-    if (selection.some((id) => !remainingIds.has(id))) {
-      this.engine.setSelection(selection.filter((id) => remainingIds.has(id)));
-    }
     this.engine.requestRender("tileset-tile-unloaded");
   }
   hasPendingVisibleTargets() {
@@ -9271,7 +11727,6 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
         this.failedLodFallbacks.delete(fallbackId);
     }
     this.visibleCoverageIds = targetIds;
-    this.reconcileSelectionVisibility();
     this.engine.requestRender("tileset-visible-target-committed");
     if (!this.readySettled) {
       this.readySettled = true;
@@ -9309,17 +11764,6 @@ var ICETilesetHandle = class extends ICEEventDispatcher {
     }
     return visible;
   }
-  reconcileSelectionVisibility() {
-    const visibleIds = /* @__PURE__ */ new Set();
-    for (const child of this.scene.children) {
-      collectVisibleNodeAndSelectionIDs(child, visibleIds);
-    }
-    const selection = this.engine.getSelection();
-    const visibleSelection = selection.filter((id) => visibleIds.has(id));
-    if (visibleSelection.length !== selection.length) {
-      this.engine.setSelection(visibleSelection);
-    }
-  }
   rejectReadyIfVisibleSetFailed() {
     if (this.readySettled || !this.workSet)
       return;
@@ -9728,34 +12172,6 @@ function collectNodeIDs(node, output) {
   for (const child of node.children)
     collectNodeIDs(child, output);
 }
-function collectNodeAndSelectionIDs(node, output) {
-  output.add(node.id);
-  if (node instanceof ICEMesh)
-    output.add(node.selectionId);
-  if (node instanceof ICERenderBatch) {
-    for (const selectionId of node.semanticSelectionIds) {
-      output.add(selectionId);
-    }
-  }
-  for (const child of node.children) {
-    collectNodeAndSelectionIDs(child, output);
-  }
-}
-function collectVisibleNodeAndSelectionIDs(node, output) {
-  if (!node.visible)
-    return;
-  output.add(node.id);
-  if (node instanceof ICEMesh)
-    output.add(node.selectionId);
-  if (node instanceof ICERenderBatch) {
-    for (const selectionId of node.semanticSelectionIds) {
-      output.add(selectionId);
-    }
-  }
-  for (const child of node.children) {
-    collectVisibleNodeAndSelectionIDs(child, output);
-  }
-}
 function throwIfAborted(signal) {
   if (signal?.aborted)
     throw abortedTilesetError();
@@ -9766,6 +12182,72 @@ function isAbortError(error) {
 function abortedTilesetError() {
   return new Error("ICE3_TILESET_ABORTED: Tileset loading was aborted");
 }
+
+// packages/runtime/dist/asset/ICEPreviewPacketLoader.js
+var ICEPreviewPacketLoader = class {
+  fetcher;
+  pinGeometry;
+  geometries = /* @__PURE__ */ new Map();
+  publishedScene = null;
+  constructor(options = {}) {
+    const normalized = typeof options === "function" ? { fetch: options } : options;
+    this.fetcher = normalized.fetch ?? globalThis.fetch.bind(globalThis);
+    this.pinGeometry = normalized.pinGeometry;
+  }
+  get scene() {
+    return this.publishedScene;
+  }
+  get currentGeometries() {
+    return this.geometries;
+  }
+  async load(url, current) {
+    let bytes;
+    try {
+      const response = await this.fetcher(url, {
+        headers: {
+          accept: "application/vnd.ice3.preview-geometry; version=1"
+        }
+      });
+      if (!response.ok) {
+        return { kind: "fallback", reason: "packet-unavailable" };
+      }
+      bytes = new Uint8Array(await response.arrayBuffer());
+    } catch {
+      return { kind: "fallback", reason: "packet-unavailable" };
+    }
+    let incoming;
+    try {
+      incoming = parsePreviewGeometryPacket(bytes);
+    } catch {
+      return { kind: "fallback", reason: "packet-invalid" };
+    }
+    let packet = incoming;
+    if (incoming.parentRevision !== null) {
+      if (!current || incoming.parentRevision !== current.revision) {
+        return { kind: "fallback", reason: "packet-revision-mismatch" };
+      }
+      packet = applyPreviewGeometryDelta(current, incoming);
+    }
+    let built;
+    try {
+      built = buildPreviewPacketScene(packet, this.geometries);
+      if (this.pinGeometry) {
+        for (const [geometryId, update] of built.geometryUpdates) {
+          const geometry = built.geometries.get(geometryId);
+          if (!geometry) {
+            throw new Error("ICE3_PREVIEW_PACKET_INVALID: geometry is missing");
+          }
+          this.pinGeometry(geometry, update);
+        }
+      }
+    } catch {
+      return { kind: "fallback", reason: "packet-invalid" };
+    }
+    this.geometries = built.geometries;
+    this.publishedScene = built.scene;
+    return { kind: "packet", packet };
+  }
+};
 export {
   ICE3,
   ICEAssetLoader,
@@ -9778,13 +12260,31 @@ export {
   ICENode,
   ICEOrbitController,
   ICEPerspectiveCamera,
+  ICEPreviewPacketLoader,
   ICEScene,
   ICEScreenLayer,
   ICETilesetHandle,
   ICETilesetLoader,
   ICETypeRegistry,
   ICEWorldLayer,
+  collectSceneItems,
   deserializeScene,
   serializeScene
 };
+//! 阴影视锥：按场景包围盒拟合方向光的正交投影。
+//!
+//! 早期实现把光照视锥写死成 860 米见方、960 米深。两个后果都很贵：
+//! 2048 的深度图摊到 860 米是每纹素 0.42 米（薄墙的影子直接消失），
+//! 而深度偏差 0.0015 在 960 米的跨度上等于 1.4 米，短影子被整段吃掉。
+//! 视锥贴合场景后，偏差回到"厘米"量级，贴图分辨率也才有意义。
+//! 方向光阴影贴图。
+//! 一次深度 pass 把场景从光源方向渲染进深度纹理，主 pass 再按世界坐标比较深度。
+//! 只处理单方向光、单张贴图；视锥按场景包围盒拟合（见 ShadowFrustum）。
+//! 场景包围盒：给阴影视锥用。
+//! 引擎里没有现成的场景 bounds，而阴影视锥必须贴合实际内容——写死范围会让
+//! 深度精度和贴图分辨率一起浪费（见 ShadowFrustum）。这里按"几何局部包围盒
+//! 缓存 + 世界矩阵变换"累加，避免每帧扫描几十万个顶点。
+//! 相机深度通道：屏幕空间遮蔽的来源。
+//! 从**相机**方向渲染一遍深度。必须覆盖全部几何路径——瓦片走渲染批次，其余走实例化
+//! 批次；只画一条会让深度图大半是空的（SPEC-007）。
 //# sourceMappingURL=index.js.map