prts-terrarchive 0.2.0

package/ui/rhine/original/array-occlusion.ts

@@ -0,0 +1,166 @@
+import * as THREE from "three";
+
+type Occluder = {
+  index: number; valid: boolean;
+  corners: THREE.Vector3[]; planes: THREE.Plane[];
+  minX: number; minY: number; maxX: number; maxY: number;
+};
+const GRID = 16;
+
+/** A verified solid rectangle, not a transparent cover or a mesh bounding box. */
+export function substrateRectangle(geometry: THREE.BufferGeometry) {
+  const positions = geometry.getAttribute("position"), indices = geometry.index;
+  if (!positions || !indices) return undefined;
+  let front = -Infinity;
+  for (let i = 0; i < positions.count; i++) front = Math.max(front, positions.getZ(i));
+  const points = new Map<string, THREE.Vector3>(), triangles: THREE.Vector3[][] = [];
+  for (let i = 0; i < indices.count; i += 3) {
+    const vertices = [indices.getX(i), indices.getX(i + 1), indices.getX(i + 2)];
+    if (!vertices.every(index => Math.abs(positions.getZ(index) - front) < 1e-6)) continue;
+    const triangle = vertices.map(index => new THREE.Vector3().fromBufferAttribute(positions, index));
+    for (const point of triangle) points.set(`${point.x},${point.y}`, point);
+    triangles.push(triangle);
+  }
+  if (triangles.length !== 2 || points.size !== 4) return undefined;
+  const shared = triangles[0].filter(a => triangles[1].some(b => a.equals(b)));
+  if (shared.length !== 2 || shared[0].x === shared[1].x || shared[0].y === shared[1].y) return undefined;
+  const bounds = new THREE.Box3().setFromPoints([...points.values()]);
+  const width = bounds.max.x - bounds.min.x, height = bounds.max.y - bounds.min.y;
+  if (width <= 0 || height <= 0) return undefined;
+  if ([...points.values()].some(p => ![bounds.min.x, bounds.max.x].includes(p.x)
+    || ![bounds.min.y, bounds.max.y].includes(p.y))) return undefined;
+  const centers = triangles.map(t => t[0].clone().add(t[1]).add(t[2]).multiplyScalar(1 / 3));
+  const area = triangles.reduce((sum, t) => sum + new THREE.Triangle(...t as [THREE.Vector3, THREE.Vector3, THREE.Vector3]).getArea(), 0);
+  if (Math.abs(area - width * height) > 1e-5 || centers[0].distanceTo(centers[1]) < 1e-5) return undefined;
+  return bounds;
+}
+
+/** Conservative camera occlusion volumes behind the array's opaque substrates. */
+export class ArrayOcclusion {
+  private readonly occluders: Occluder[];
+  private readonly grid: Uint32Array;
+  private readonly gridCounts = new Uint32Array(GRID * GRID);
+  private readonly capacity: number;
+  private readonly eye = new THREE.Vector3();
+  private readonly direction = new THREE.Vector3();
+  private readonly center = new THREE.Vector3();
+  private readonly half = new THREE.Vector3();
+  private readonly worldCenter = new THREE.Vector3();
+  private readonly point = new THREE.Vector3();
+  private readonly extrusion = new THREE.Vector3();
+  private readonly projection = new THREE.Matrix4();
+  private readonly view = new THREE.Matrix4();
+  private perspective = true;
+  private pixelScale = 0;
+  private near = 0;
+  private readonly rectangle: THREE.Box3;
+  tested = 0;
+  rejected = 0;
+
+  constructor(rectangle: THREE.Box3, capacity: number) {
+    this.rectangle = rectangle.clone();
+    this.capacity = capacity;
+    this.grid = new Uint32Array(GRID * GRID * capacity);
+    this.occluders = Array.from({ length: capacity }, (_, index) => ({
+      index, valid: false,
+      corners: Array.from({ length: 4 }, () => new THREE.Vector3()),
+      planes: Array.from({ length: 5 }, () => new THREE.Plane()),
+      minX: 0, minY: 0, maxX: 0, maxY: 0,
+    }));
+  }
+
+  update(camera: THREE.Camera, matrices: readonly THREE.Matrix4[], active: Uint32Array, count: number, pixelHeight: number) {
+    this.tested = this.rejected = 0;
+    this.gridCounts.fill(0);
+    this.eye.setFromMatrixPosition(camera.matrixWorld);
+    camera.getWorldDirection(this.direction);
+    this.perspective = camera instanceof THREE.PerspectiveCamera;
+    this.near = (camera as THREE.PerspectiveCamera).near ?? 0.1;
+    this.view.copy(camera.matrixWorldInverse);
+    this.projection.multiplyMatrices(camera.projectionMatrix, this.view);
+    // Three output pixels plus a world-space guard protect antialiasing and
+    // the existing thin cover's refracted samples near an occluder's edge.
+    this.pixelScale = pixelHeight > 0 ? 6 / (Math.abs(camera.projectionMatrix.elements[5]) * pixelHeight) : Infinity;
+    for (let i = 0; i < count; i++) {
+      const index = active[i], object = this.occluders[index], matrix = matrices[index];
+      const { min, max } = this.rectangle, corners = object.corners;
+      corners[0].set(min.x, min.y, max.z).applyMatrix4(matrix);
+      corners[1].set(max.x, min.y, max.z).applyMatrix4(matrix);
+      corners[2].set(max.x, max.y, max.z).applyMatrix4(matrix);
+      corners[3].set(min.x, max.y, max.z).applyMatrix4(matrix);
+      object.minX = object.minY = Infinity; object.maxX = object.maxY = -Infinity;
+      object.valid = true;
+      this.center.set(0, 0, 0);
+      for (const corner of corners) {
+        this.center.add(corner);
+        this.point.copy(corner).applyMatrix4(this.view);
+        if (-this.point.z <= this.near + 0.01) object.valid = false;
+        this.point.copy(corner).applyMatrix4(this.projection);
+        object.minX = Math.min(object.minX, this.point.x); object.maxX = Math.max(object.maxX, this.point.x);
+        object.minY = Math.min(object.minY, this.point.y); object.maxY = Math.max(object.maxY, this.point.y);
+      }
+      if (!object.valid) continue;
+      if (object.minX > 1 || object.maxX < -1 || object.minY > 1 || object.maxY < -1) continue;
+      this.center.multiplyScalar(0.25);
+      const front = object.planes[4].setFromCoplanarPoints(corners[0], corners[1], corners[2]);
+      if (Math.abs(front.normal.dot(this.direction)) < 0.01) continue;
+      // All five planes point into the hidden volume. Rejects are valid only
+      // when the entire candidate box is strictly inside this one volume.
+      if (this.perspective ? front.distanceToPoint(this.eye) > 0 : front.normal.dot(this.direction) < 0) front.negate();
+      for (let edge = 0; edge < 4; edge++) {
+        const a = corners[edge], b = corners[(edge + 1) % 4];
+        this.extrusion.copy(a).add(this.direction);
+        const plane = object.planes[edge].setFromCoplanarPoints(a, b, this.perspective ? this.eye : this.extrusion);
+        if (plane.distanceToPoint(this.center) < 0) plane.negate();
+      }
+      const left = Math.max(0, Math.floor((object.minX + 1) * GRID / 2));
+      const right = Math.min(GRID - 1, Math.floor((object.maxX + 1) * GRID / 2));
+      const bottom = Math.max(0, Math.floor((object.minY + 1) * GRID / 2));
+      const top = Math.min(GRID - 1, Math.floor((object.maxY + 1) * GRID / 2));
+      for (let y = bottom; y <= top; y++) for (let x = left; x <= right; x++) {
+        const cell = y * GRID + x;
+        this.grid[cell * this.capacity + this.gridCounts[cell]++] = index;
+      }
+    }
+  }
+
+  hidden(bounds: THREE.Box3, matrix: THREE.Matrix4, index: number) {
+    this.tested++;
+    if (bounds.isEmpty() || !Number.isFinite(this.pixelScale)) return false;
+    bounds.getCenter(this.center); bounds.getSize(this.half).multiplyScalar(0.5);
+    this.worldCenter.copy(this.center).applyMatrix4(matrix);
+    this.point.copy(this.worldCenter).applyMatrix4(this.view);
+    const margin = Math.max(0.08, this.pixelScale * (this.perspective ? Math.max(0, -this.point.z) : 1));
+    const m = matrix.elements, h = this.half, v = this.view.elements;
+    // OBB support along camera Z gives the nearest corner depth directly.
+    // The five occluder planes below already prove screen coverage; projecting
+    // all eight corners again adds work without strengthening that proof.
+    const depthRadius = Math.abs(v[2] * m[0] + v[6] * m[1] + v[10] * m[2]) * h.x
+      + Math.abs(v[2] * m[4] + v[6] * m[5] + v[10] * m[6]) * h.y
+      + Math.abs(v[2] * m[8] + v[6] * m[9] + v[10] * m[10]) * h.z;
+    if (-this.point.z - depthRadius <= this.near + margin) return false;
+    this.point.copy(this.worldCenter).applyMatrix4(this.projection);
+    const x = Math.floor((this.point.x + 1) * GRID / 2), y = Math.floor((this.point.y + 1) * GRID / 2);
+    // A volume covering the candidate must also cover its projected center.
+    // Spatial bins only reduce the candidate list; the exact five-plane proof
+    // below still decides visibility, with the same conservative margin.
+    if (x < 0 || x >= GRID || y < 0 || y >= GRID) return false;
+    const cell = y * GRID + x, candidateCount = this.gridCounts[cell], start = cell * this.capacity;
+    if (!candidateCount) return false;
+    for (let candidate = 0; candidate < candidateCount; candidate++) {
+      const object = this.occluders[this.grid[start + candidate]];
+      if (object.index === index) continue;
+      let covered = true;
+      for (let p = 4; p >= 0; p--) {
+        const plane = object.planes[p];
+        const n = plane.normal;
+        const radius = Math.abs(n.x * m[0] + n.y * m[1] + n.z * m[2]) * h.x
+          + Math.abs(n.x * m[4] + n.y * m[5] + n.z * m[6]) * h.y
+          + Math.abs(n.x * m[8] + n.y * m[9] + n.z * m[10]) * h.z;
+        if (plane.distanceToPoint(this.worldCenter) - radius <= margin) { covered = false; break; }
+      }
+      if (covered) { this.rejected++; return true; }
+    }
+    return false;
+  }
+}

package/ui/rhine/original/array-shell.ts

@@ -0,0 +1,38 @@
+import * as THREE from "three";
+
+/** Partition authored faces without cutting triangles or changing their normals.
+ * Fine bevels occupy four corners; a small shared group keeps faces spanning
+ * quadrant boundaries. Every original triangle occurs in exactly one region.
+ */
+export function splitArrayShell(surface: string, source: THREE.BufferGeometry) {
+  if (!["Frosted_Polymer", "Ivory_Edges"].includes(surface) || !source.index) return undefined;
+  const position = source.getAttribute("position");
+  if (!position) return undefined;
+  const bounds = new THREE.Box3().setFromBufferAttribute(position as THREE.BufferAttribute);
+  const center = bounds.getCenter(new THREE.Vector3());
+  const regions = Array.from({ length: 5 }, () => [] as number[]);
+  for (let i = 0; i < source.index.count; i += 3) {
+    const vertices = [source.index.getX(i), source.index.getX(i + 1), source.index.getX(i + 2)];
+    const side = vertices.map(index => (position.getX(index) < center.x ? 0 : 1)
+      + (position.getY(index) < center.y ? 0 : 2));
+    const region = side.every(value => value === side[0]) ? side[0] : 4;
+    regions[region].push(...vertices);
+  }
+  if (regions.filter(region => region.length).length < 2) return undefined;
+  return regions.flatMap((indices, region) => {
+    if (!indices.length) return [];
+    const geometry = new THREE.BufferGeometry(), vertices: number[] = [], remap = new Map<number, number>();
+    const compact = indices.map(index => {
+      if (!remap.has(index)) { remap.set(index, vertices.length); vertices.push(index); }
+      return remap.get(index)!;
+    });
+    for (const [name, attribute] of Object.entries(source.attributes)) {
+      const values = new Float32Array(vertices.length * attribute.itemSize);
+      for (let i = 0; i < vertices.length; i++) for (let c = 0; c < attribute.itemSize; c++)
+        values[i * attribute.itemSize + c] = attribute.getComponent(vertices[i], c);
+      geometry.setAttribute(name, new THREE.BufferAttribute(values, attribute.itemSize));
+    }
+    geometry.setIndex(compact); geometry.computeBoundingBox(); geometry.computeBoundingSphere();
+    return [{ geometry, suffix: region === 4 ? "_Spanning" : `_Region_${region}` }];
+  });
+}

package/ui/rhine/original/array-visibility.ts

@@ -0,0 +1,309 @@
+import * as THREE from "three";
+import { ArrayOcclusion, substrateRectangle } from "./array-occlusion.ts";
+
+const FRUSTUM_PADDING = 0.35;
+// A companion attribute makes WebGLGeometries upload the shadow matrices before
+// onBeforeShadow. It is not a shader input; binding uses mesh.instanceMatrix.
+const SHADOW_MATRIX_ATTRIBUTE = "rhineShadowMatrix";
+type ShadowBuffers = {
+  geometry: THREE.BufferGeometry;
+  camera: THREE.InstancedBufferAttribute;
+  shadow: THREE.InstancedBufferAttribute;
+};
+
+type Batch = {
+  mesh: THREE.InstancedMesh;
+  indices: Uint32Array;
+  count: number;
+  filtered: Uint32Array;
+  occluded: number;
+  outside: number;
+  shadowCount: number;
+  triangles: number;
+  shadowBuffers?: ShadowBuffers;
+
+};
+type DetailLOD = {
+  high: THREE.InstancedMesh; low: THREE.InstancedMesh;
+  featureSize: number; enterBelow: number; leaveAbove: number;
+  levels: Uint8Array; highIndices: Uint32Array; lowIndices: Uint32Array;
+  highCount: number; lowCount: number;
+};
+
+/**
+ * Keep logical cassette poses separate from compact GPU instance slots.
+ * Batch transforms must be identity: authored geometry and slot matrices share
+ * world space. Complete-cassette bounds provide the broad phase; flagged parts
+ * can be culled individually. Shadow casters use an independent light-frustum list.
+ * Pass every shadow light frustum, or omit the list to retain all active casters.
+ */
+export class ArrayVisibility {
+  private readonly matrices: THREE.Matrix4[];
+  private readonly active: Uint8Array;
+  private readonly activeIndices: Uint32Array;
+  private readonly visibleIndices: Uint32Array;
+  private readonly submitted: Uint8Array;
+  private readonly shadowHooks = new WeakSet<THREE.InstancedMesh>();
+  private readonly shadowBuffers = new WeakMap<THREE.InstancedMesh, ShadowBuffers>();
+  private readonly shadowSubmitted: Uint8Array;
+  private readonly cardBounds = new THREE.Box3();
+  private readonly worldBounds = new THREE.Box3();
+  private readonly viewProjection = new THREE.Matrix4();
+  private readonly frustum = new THREE.Frustum();
+  private batches: Batch[] = [];
+  private readonly batchByMesh = new Map<THREE.InstancedMesh, Batch>();
+  private activeSlots = 0;
+  private visibleSlots = 0;
+  private shadowSlots = 0;
+  private cameraTriangles = 0;
+  private shadowTriangles = 0;
+  private shadowOnlyTriangles = 0;
+  private shadowCulledTriangles = 0;
+  private readonly detailLODs: DetailLOD[] = [];
+  private readonly lodPoint = new THREE.Vector3();
+  private occlusion?: ArrayOcclusion;
+
+
+  setOpaqueSubstrate(geometry: THREE.BufferGeometry) {
+    const rectangle = substrateRectangle(geometry);
+    this.occlusion = rectangle ? new ArrayOcclusion(rectangle, this.capacity) : undefined;
+  }
+
+  addDetailLOD(high: THREE.InstancedMesh, low: THREE.InstancedMesh,
+    featureSize: number, enterBelow: number, leaveAbove: number) {
+    this.detailLODs.push({ high, low, featureSize, enterBelow, leaveAbove,
+      levels: new Uint8Array(this.capacity), highIndices: new Uint32Array(this.capacity),
+      lowIndices: new Uint32Array(this.capacity), highCount: 0, lowCount: 0 });
+  }
+
+  constructor(readonly capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 0)
+      throw new RangeError("Array capacity must be a non-negative integer.");
+    this.matrices = Array.from({ length: capacity }, () => new THREE.Matrix4());
+    this.active = new Uint8Array(capacity);
+    this.activeIndices = new Uint32Array(capacity);
+    this.visibleIndices = new Uint32Array(capacity);
+    this.submitted = new Uint8Array(capacity);
+    this.shadowSubmitted = new Uint8Array(capacity);
+  }
+
+  setSlot(index: number, matrix: THREE.Matrix4, active: boolean) {
+    this.matrixAt(index).copy(matrix);
+    this.active[index] = active ? 1 : 0;
+  }
+
+  /** Borrow the full authored pose, including hidden and culled slots. */
+  matrixAt(index: number): THREE.Matrix4 {
+    if (!Number.isInteger(index) || index < 0 || index >= this.capacity)
+      throw new RangeError("Array slot is outside the logical pool.");
+    return this.matrices[index];
+  }
+
+  /** Call after all geometry/bake batches have been created. */
+  prepare(instances: readonly THREE.InstancedMesh[]) {
+    this.cardBounds.makeEmpty();
+    this.batchByMesh.clear();
+    this.batches = instances.map((mesh) => {
+      if (mesh.instanceMatrix.count < this.capacity)
+        throw new RangeError("Instance buffer is smaller than the logical pool.");
+      if (mesh.geometry.boundingBox === null) mesh.geometry.computeBoundingBox();
+      if (mesh.geometry.boundingBox) this.cardBounds.union(mesh.geometry.boundingBox);
+      let buffers = this.shadowBuffers.get(mesh);
+      if (mesh.castShadow && (!buffers || buffers.geometry !== mesh.geometry)) {
+        // Keep the upload-only attribute off shared selected/baked geometries.
+        const geometry = mesh.geometry.clone();
+        const shadow = new THREE.InstancedBufferAttribute(new Float32Array(this.capacity * 16), 16)
+          .setUsage(THREE.DynamicDrawUsage);
+        geometry.setAttribute(SHADOW_MATRIX_ATTRIBUTE, shadow);
+        mesh.geometry = geometry;
+        buffers = { geometry, camera: mesh.instanceMatrix, shadow };
+        this.shadowBuffers.set(mesh, buffers);
+      }
+      const batch: Batch = { mesh, indices: this.visibleIndices, count: 0,
+        filtered: new Uint32Array(this.capacity), occluded: 0, outside: 0, shadowCount: 0,
+        triangles: (mesh.geometry.index?.count ?? mesh.geometry.attributes.position.count) / 3,
+        shadowBuffers: buffers };
+      if (mesh.castShadow && !this.shadowHooks.has(mesh)) {
+        this.shadowHooks.add(mesh);
+        const before = mesh.onBeforeShadow, after = mesh.onAfterShadow;
+        const restore = () => {
+          const current = this.batchByMesh.get(mesh);
+          if (current?.shadowBuffers) mesh.instanceMatrix = current.shadowBuffers.camera;
+          mesh.count = current?.count ?? 0;
+        };
+        mesh.onBeforeShadow = (...args) => {
+          const current = this.batchByMesh.get(mesh);
+          if (current?.shadowBuffers) mesh.instanceMatrix = current.shadowBuffers.shadow;
+          mesh.count = current?.shadowCount ?? 0;
+          try { before.apply(mesh, args); }
+          catch (error) { restore(); throw error; }
+        };
+        mesh.onAfterShadow = (...args) => {
+          try { after.apply(mesh, args); }
+          finally { restore(); }
+        };
+      }
+      this.batchByMesh.set(mesh, batch);
+      return batch;
+    });
+  }
+
+  submit(camera: THREE.Camera, instances: readonly THREE.InstancedMesh[], cull = true, pixelHeight = 0,
+    shadowFrusta?: readonly THREE.Frustum[]) {
+    if (instances.length !== this.batches.length ||
+      instances.some((mesh, index) => mesh !== this.batches[index].mesh))
+      this.prepare(instances);
+    camera.updateWorldMatrix(true, false);
+    this.viewProjection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+    this.frustum.setFromProjectionMatrix(
+      this.viewProjection, camera.coordinateSystem, camera.reversedDepth,
+    );
+    this.activeSlots = 0;
+    this.visibleSlots = 0;
+    const testBounds = cull && !this.cardBounds.isEmpty();
+    for (let index = 0; index < this.capacity; index++) {
+      if (!this.active[index]) continue;
+      this.activeIndices[this.activeSlots++] = index;
+      if (testBounds) {
+        this.worldBounds.copy(this.cardBounds)
+          .applyMatrix4(this.matrices[index]).expandByScalar(FRUSTUM_PADDING);
+        if (!this.frustum.intersectsBox(this.worldBounds)) continue;
+      }
+      this.visibleIndices[this.visibleSlots++] = index;
+    }
+    // A substrate covering an on-screen point necessarily intersects this
+    // conservative complete-card frustum list. Off-screen casters stay in the
+    // separate shadow list and do not need camera-occlusion volumes.
+    this.occlusion?.update(camera, this.matrices, this.visibleIndices, this.visibleSlots, pixelHeight);
+    for (const lod of this.detailLODs) {
+      lod.highCount = lod.lowCount = 0;
+      for (let index = 0; index < this.visibleSlots; index++) {
+        const logical = this.visibleIndices[index];
+        this.lodPoint.set(0, 1.85, 0).applyMatrix4(this.matrices[logical]).applyMatrix4(camera.matrixWorldInverse);
+        const depth = camera instanceof THREE.PerspectiveCamera ? Math.max(0.01, -this.lodPoint.z - 3) : 1;
+        const pixels = pixelHeight > 0 ? lod.featureSize * Math.abs(camera.projectionMatrix.elements[5]) * pixelHeight / (2 * depth) : Infinity;
+        const low = pixels < (lod.levels[logical] ? lod.leaveAbove : lod.enterBelow);
+        lod.levels[logical] = low ? 1 : 0;
+        if (low) lod.lowIndices[lod.lowCount++] = logical;
+        else lod.highIndices[lod.highCount++] = logical;
+      }
+    }
+    this.shadowSlots = 0;
+    this.cameraTriangles = this.shadowTriangles = this.shadowOnlyTriangles = this.shadowCulledTriangles = 0;
+    this.shadowSubmitted.fill(0);
+    for (const batch of this.batches) {
+      const { mesh } = batch;
+      // A renderer error can interrupt a shadow draw before onAfterShadow.
+      // Start every submission from the owned camera buffer in that case too.
+      if (batch.shadowBuffers) mesh.instanceMatrix = batch.shadowBuffers.camera;
+      batch.indices = this.visibleIndices;
+      batch.count = this.visibleSlots;
+      batch.shadowCount = 0;
+      const lod = this.detailLODs.find(item => item.high === mesh || item.low === mesh);
+      if (lod) {
+        batch.indices = mesh === lod.high ? lod.highIndices : lod.lowIndices;
+        batch.count = mesh === lod.high ? lod.highCount : lod.lowCount;
+      }
+      batch.occluded = batch.outside = 0;
+      if (this.occlusion && mesh.userData.occlusionCull) {
+        let kept = 0;
+        for (let i = 0; i < batch.count; i++) {
+          const logical = batch.indices[i];
+          this.worldBounds.copy(mesh.geometry.boundingBox!).applyMatrix4(this.matrices[logical]).expandByScalar(FRUSTUM_PADDING);
+          if (cull && !this.frustum.intersectsBox(this.worldBounds)) batch.outside++;
+          else if (this.occlusion.hidden(mesh.geometry.boundingBox!, this.matrices[logical], logical)) batch.occluded++;
+          else batch.filtered[kept++] = logical;
+        }
+        batch.indices = batch.filtered; batch.count = kept;
+      }
+      if (mesh.castShadow) this.submitted.fill(0);
+      for (let index = 0; index < batch.count; index++) {
+        const logical = batch.indices[index];
+        mesh.setMatrixAt(index, this.matrices[logical]);
+        if (mesh.castShadow) this.submitted[logical] = 1;
+      }
+      if (mesh.castShadow && batch.shadowBuffers) {
+        const attribute = batch.shadowBuffers.shadow;
+        // Use the union when there are multiple shadow lights. The main camera
+        // list is independent: a visible object need not enter a light's map.
+        for (let index = 0; index < this.activeSlots; index++) {
+          const logical = this.activeIndices[index];
+          if (cull && shadowFrusta?.length) {
+            this.worldBounds.copy(mesh.geometry.boundingBox!).applyMatrix4(this.matrices[logical])
+              .expandByScalar(FRUSTUM_PADDING);
+            if (!shadowFrusta.some(frustum => frustum.intersectsBox(this.worldBounds))) continue;
+          }
+          this.matrices[logical].toArray(attribute.array, batch.shadowCount++ * 16);
+          if (!this.submitted[logical]) this.shadowOnlyTriangles += batch.triangles;
+          if (!this.shadowSubmitted[logical]) { this.shadowSubmitted[logical] = 1; this.shadowSlots++; }
+        }
+        attribute.clearUpdateRanges();
+        if (batch.shadowCount > 0) {
+          attribute.addUpdateRange(0, batch.shadowCount * 16);
+          attribute.needsUpdate = true;
+        }
+        mesh.userData.shadowInstanceCount = batch.shadowCount;
+        this.shadowTriangles += batch.shadowCount * batch.triangles;
+        this.shadowCulledTriangles += (this.activeSlots - batch.shadowCount) * batch.triangles;
+      }
+      this.cameraTriangles += batch.count * batch.triangles;
+      mesh.count = batch.count;
+      mesh.instanceMatrix.clearUpdateRanges();
+      if (batch.count > 0) {
+        mesh.instanceMatrix.addUpdateRange(0, batch.count * 16);
+        mesh.instanceMatrix.needsUpdate = true;
+      }
+      // setMatrixAt does not invalidate these. Raycasting also uses the sphere
+      // when frustumCulled is false, so both must follow compaction and motion.
+      mesh.boundingBox = null;
+      mesh.boundingSphere = null;
+    }
+  }
+
+  logicalIndex(mesh: THREE.InstancedMesh, instanceId: number): number | undefined {
+    const batch = this.batchByMesh.get(mesh);
+    if (!batch || !Number.isInteger(instanceId) || instanceId < 0 || instanceId >= batch.count)
+      return undefined;
+    return batch.indices[instanceId];
+  }
+
+  /** Geometry inventory per pass; actual frame submissions can draw it again. */
+  triangleStats() {
+    return { cameraTrianglesPerPass: this.cameraTriangles,
+      shadowTrianglesPerPass: this.shadowTriangles,
+      shadowOnlyTrianglesPerPass: this.shadowOnlyTriangles,
+      shadowCulledTrianglesPerPass: this.shadowCulledTriangles };
+  }
+
+  getStats() {
+    return {
+      capacity: this.capacity,
+      activeSlots: this.activeSlots,
+      visibleSlots: this.visibleSlots,
+      culledSlots: this.activeSlots - this.visibleSlots,
+      shadowSlots: this.shadowSlots,
+      ...this.triangleStats(),
+      ...(this.detailLODs.length ? { lod: this.detailLODs.map(item => ({
+        name: item.high.name, high: this.batchByMesh.get(item.high)?.count ?? 0,
+        low: this.batchByMesh.get(item.low)?.count ?? 0,
+        enterBelowPixels: item.enterBelow, leaveAbovePixels: item.leaveAbove,
+      })) } : {}),
+      ...(this.occlusion ? { occlusion: {
+        testedParts: this.occlusion.tested, culledParts: this.occlusion.rejected,
+        outsideParts: this.batches.reduce((sum, batch) => sum + batch.outside, 0),
+        savedTrianglesPerPass: this.batches.reduce((sum, batch) => sum + (batch.occluded + batch.outside)
+          * (batch.mesh.geometry.index?.count ?? batch.mesh.geometry.attributes.position.count) / 3, 0),
+        parts: this.batches.filter(batch => batch.mesh.userData.occlusionCull).map(batch => ({
+          name: batch.mesh.name, visible: batch.count, culled: batch.occluded, outside: batch.outside,
+          trianglesPerInstance: batch.triangles, submittedTrianglesPerPass: batch.count * batch.triangles,
+        })),
+      } } : {}),
+      batches: this.batches.map(({ mesh, count, shadowCount }) => ({
+        name: mesh.name,
+        castShadow: mesh.castShadow,
+        count,
+        ...(mesh.castShadow ? { shadowCount } : {}),
+      })),
+    };
+  }
+}

package/ui/rhine/original/asset-url.ts

@@ -0,0 +1,4 @@
+/** Host integration only: preserve upstream asset paths under the plugin base. */
+let base = '/';
+export const setAssetBase = (value: string) => { base = `${value.replace(/\/$/, '')}/`; };
+export const assetUrl = (path: string) => `${base}${path.replace(/^\//, '')}`;

package/ui/rhine/original/brand.ts

@@ -0,0 +1,12 @@
+// One shared mark for the interface and the printed archive label.
+const paths = `<path d="M156 75C127 48 103 15 70 15C37 15 15 39 15 70S38 128 70 128C103 128 127 96 176 52M155 75C182 99 208 128 240 128C273 128 295 105 295 73S273 15 240 15C221 15 207 23 192 38" fill="none" stroke="currentColor" stroke-width="26"/><path d="M44 70h50M69 45v50M219 70h44" fill="none" stroke="currentColor" stroke-width="15"/>`;
+export const labelMarkSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 310 145" color="#171713">${paths}</svg>`;
+export const logo = `<svg viewBox="0 0 310 185" aria-label="Rhine Lab" role="img">${paths}<text x="165" y="174" text-anchor="middle" font-family="MiSans,sans-serif" font-size="16" font-weight="700" letter-spacing="22">RHINE·LAB</text></svg>`;
+// The same Bezier contour, continuous for the opening's moving draw/erase ends.
+// Its small printed gap is animated with stroke dashes, not baked into the path.
+export const bootMarkContour =
+  "M295 73C295 41 273 15 240 15C221 15 207 23 192 38C186 43 181 47 176 52C127 96 103 128 70 128C38 128 15 101 15 70C15 39 37 15 70 15C103 15 127 48 156 75C182 99 208 128 240 128C273 128 295 105 295 73Z";
+
+// Optical spacing for this fixed wordmark, measured from the reference glyphs.
+const analysisPositions = [2, 28, 55, 81, 103, 129, 154, 166];
+export const brandHeading = `<h1>RHINE LAB</h1><div>SYNTHESIZE INFORMATION</div><p><span class="brand-analysis" role="img" aria-label="ANALYSIS">${[..."ANALYSIS"].map((letter, i) => `<span aria-hidden="true" style="left:${analysisPositions[i]}px">${letter}</span>`).join("")}</span> <b>OS</b></p>`;

package/ui/rhine/original/cassette-lod.ts

@@ -0,0 +1,81 @@
+import * as THREE from "three";
+
+/** Independent screws allow the buried lower screw to be omitted entirely. */
+export function splitCassetteFasteners(source: THREE.BufferGeometry) {
+  if (!source.index) return undefined;
+  const positions = source.getAttribute("position"), top: number[] = [], bottom: number[] = [];
+  for (let offset = 0; offset < source.index.count; offset += 3) {
+    const indices = [source.index.getX(offset), source.index.getX(offset + 1), source.index.getX(offset + 2)];
+    const upper = indices.every(index => positions.getY(index) > 1.85);
+    const lower = indices.every(index => positions.getY(index) < 1.85);
+    if (!upper && !lower) return undefined;
+    (upper ? top : bottom).push(...indices);
+  }
+  if (!top.length || !bottom.length) return undefined;
+  return [top, bottom].map(indices => {
+    // Compact attributes as well as indices: BufferGeometry computes bounds
+    // from all vertices, including unreferenced ones.
+    const geometry = new THREE.BufferGeometry(), remap = new Map<number, number>();
+    const vertices: number[] = [], compact = indices.map(index => {
+      if (!remap.has(index)) { remap.set(index, vertices.length); vertices.push(index); }
+      return remap.get(index)!;
+    });
+    for (const [name, attribute] of Object.entries(source.attributes)) {
+      const values = new Float32Array(vertices.length * attribute.itemSize);
+      for (let i = 0; i < vertices.length; i++) for (let c = 0; c < attribute.itemSize; c++)
+        values[i * attribute.itemSize + c] = attribute.getComponent(vertices[i], c);
+      geometry.setAttribute(name, new THREE.BufferAttribute(values, attribute.itemSize));
+    }
+    geometry.setIndex(compact); geometry.computeBoundingBox(); geometry.computeBoundingSphere();
+    return geometry;
+  });
+}
+
+/** Reduce outer-ring tessellation while keeping the screw recess and relief exact. */
+export function createCassetteLOD(surface: string, source: THREE.BufferGeometry) {
+  if (surface !== "Titanium_Fasteners" || !source.index) return undefined;
+  const position = source.getAttribute("position");
+  const originalTriangles = source.index.count / 3;
+  if (originalTriangles < 500) return undefined;
+  const bounds = [new THREE.Box3(), new THREE.Box3()];
+  const point = new THREE.Vector3();
+  for (let i = 0; i < position.count; i++) {
+    point.fromBufferAttribute(position, i);
+    bounds[point.x < 0 ? 0 : 1].expandByPoint(point);
+  }
+  // These are the two authored circular fasteners. A changed asset keeps its
+  // original mesh until its replacement can be validated independently.
+  if (bounds.some(box => box.isEmpty() || Math.abs(box.max.x - box.min.x - 0.12) > 0.00001
+    || Math.abs(box.max.y - box.min.y - 0.12) > 0.00001)) return undefined;
+  const centers = bounds.map(box => box.getCenter(new THREE.Vector3()));
+  const geometry = source.clone(), output = geometry.getAttribute("position"), normals = geometry.getAttribute("normal");
+  const step = Math.PI * 2 / 16;
+  for (let i = 0; i < position.count; i++) {
+    const center = centers[position.getX(i) < 0 ? 0 : 1];
+    const x = position.getX(i) - center.x, y = position.getY(i) - center.y;
+    const radius = Math.hypot(x, y);
+    if (radius <= 0.05) continue; // Recess, slots and all inner engraving stay exact.
+    const angle = Math.atan2(y, x), target = Math.round(angle / step) * step;
+    const snappedRadius = Math.round(radius * 100000) / 100000;
+    output.setXY(i, center.x + Math.cos(target) * snappedRadius, center.y + Math.sin(target) * snappedRadius);
+    if (normals) {
+      const nx = normals.getX(i), ny = normals.getY(i), delta = target - angle;
+      normals.setXY(i, nx * Math.cos(delta) - ny * Math.sin(delta), nx * Math.sin(delta) + ny * Math.cos(delta));
+    }
+  }
+  const indices: number[] = [], a = new THREE.Vector3(), b = new THREE.Vector3(), c = new THREE.Vector3();
+  for (let i = 0; i < source.index.count; i += 3) {
+    const ia = source.index.getX(i), ib = source.index.getX(i + 1), ic = source.index.getX(i + 2);
+    a.fromBufferAttribute(output, ia); b.fromBufferAttribute(output, ib); c.fromBufferAttribute(output, ic);
+    if (b.sub(a).cross(c.sub(a)).lengthSq() > 1e-20) indices.push(ia, ib, ic);
+  }
+  geometry.setIndex(indices); geometry.computeBoundingBox(); geometry.computeBoundingSphere();
+  if (source.boundingBox === null) source.computeBoundingBox();
+  const triangles = indices.length / 3;
+  if (triangles >= originalTriangles
+    || geometry.boundingBox!.min.distanceTo(source.boundingBox!.min) > 0.000001
+    || geometry.boundingBox!.max.distanceTo(source.boundingBox!.max) > 0.000001) {
+    geometry.dispose(); return undefined;
+  }
+  return { geometry, featureSize: 0.12, enterBelow: 18, leaveAbove: 22, originalTriangles, triangles };
+}

package/ui/rhine/original/data.ts

@@ -0,0 +1,21 @@
+import { ARCHIVE_LANES } from '../catalogue.ts';
+
+// Reusable positions in the authored animation, never document records.
+// Source identities, labels and per-category lengths live in the adapter.
+export const archiveColumns = [...ARCHIVE_LANES];
+export const archiveSlots = Array.from({ length: 40 }, (_, index) => ({
+  lane: Math.floor(index / 8),
+  row: 12 + index % 8,
+}));
+
+export function columnFiles(lane: number): number[] {
+  return Array.from({ length: 8 }, (_, index) => lane * 8 + index);
+}
+export function fileLocation(index: number) {
+  const { lane, row } = archiveSlots[((index % 40) + 40) % 40];
+  return { lane, row, slot: lane * 32 + row };
+}
+export function fileAtSlot(slot: number) {
+  const lane = Math.max(0, Math.min(4, Math.floor(slot / 32)));
+  return lane * 8 + Math.max(0, Math.min(7, slot % 32 - 12));
+}