@ifc-lite/viewer 1.19.0 → 1.19.1

package/src/components/mcp/HeroScene.tsx

@@ -0,0 +1,876 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * HeroScene — the hero’s living building. Real WebGL via Three.js.
+ *
+ * Twelve agent steps now, picked to span every visible primitive on the MCP
+ * surface (Discovery, Query, Validation, Mutation, BCF, bSDD, Viewer):
+ *
+ *   00  viewer_open                       neutral framing
+ *   01  model_audit                       audit badge appears
+ *   02  count_entities(group_by="type")   element-count panel slides in
+ *   03  viewer_color_by_storey            storey-0 cool blue, storey-1 warm orange
+ *   04  viewer_color_by_property(IsExt.)  outer walls vs inner walls split colour
+ *   05  viewer_isolate(IfcWall)           non-walls fade out
+ *   06  viewer_colorize(IfcWall, "#d6ff3f") chartreuse paint
+ *   07  bsdd_property_sets(IfcWall)       Pset list overlay
+ *   08  entity_create(IfcDoor)            new door slides into the south wall
+ *   09  viewer_set_section(z=2.2)         section plane clips top storey progressively
+ *   10  bcf_topic_create("missing rating") red pin appears beside a wall
+ *   11  viewer_describe_selection         info card overlays the canvas
+ *
+ * Steps own three things in parallel:
+ *
+ *   • visual scene state (driven inside this file via tweened materials,
+ *     positions, and three.js clipping planes),
+ *   • a transcript line (printed under the canvas by the parent),
+ *   • optional UI overlays (badges, pins, panels) the parent renders on
+ *     top of the canvas via the exported `HERO_STEPS` data.
+ */
+
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+
+const NIGHT = 0x0a0a0c;
+const PAPER = 0xede4d3;
+const PAPER_DIM = 0x6f6657;
+const ACCENT = 0xd6ff3f;     // chartreuse
+const ACCENT_2 = 0xff5cdc;   // magenta
+const TEAL = 0x73daca;
+const STOREY_HUE_LO = 0x4a6fa5; // cool blue
+const STOREY_HUE_HI = 0xff9e64; // warm orange
+const PROP_TRUE = 0xd6ff3f;     // outer (IsExternal=true)
+const PROP_FALSE = 0x7c7cd2;    // inner (IsExternal=false)
+const SLAB_DIM = 0x222226;
+const NEW_DOOR_HUE = 0xff5cdc;  // freshly-created door pulses magenta
+
+/** Step descriptor — `verb` carries the story-arc headline (1-2 words),
+ *  `line` is the technical tool call shown beneath it. Overlays are kept
+ *  intentionally sparse: each one shows the smallest piece of evidence
+ *  that proves the agent's action landed. */
+export interface HeroStep {
+  /** One- or two-word verb shown big in display serif. The story arc. */
+  verb: string;
+  /** Tool call line shown under the verb in mono. The detail. */
+  line: string;
+  /** Tool category badge ("Validation", "Viewer", …). */
+  family: string;
+  /** Optional overlay UI key the parent renders inside the canvas frame. */
+  overlay?:
+    | { kind: 'audit'; score: number; note: string }
+    | { kind: 'counts'; rows: Array<{ type: string; n: number }> }
+    | { kind: 'psets'; psets: string[] }
+    | { kind: 'pin'; ref: string }
+    | { kind: 'card'; ref: string; lines: string[] };
+}
+
+export const HERO_STEPS: HeroStep[] = [
+  { verb: 'Open',      line: 'viewer_open()',                                  family: 'Viewer' },
+  { verb: 'Audit',     line: 'model_audit()',                                  family: 'Validation', overlay: { kind: 'audit', score: 74, note: '1 issue' } },
+  { verb: 'Survey',    line: 'count_entities(group_by: "type")',               family: 'Query',      overlay: { kind: 'counts', rows: [
+      { type: 'Wall',   n: 8 },
+      { type: 'Window', n: 12 },
+      { type: 'Slab',   n: 3 },
+    ] } },
+  { verb: 'Layer',     line: 'viewer_color_by_storey()',                       family: 'Viewer' },
+  { verb: 'Classify',  line: 'viewer_color_by_property("IsExternal")',         family: 'Viewer' },
+  { verb: 'Focus',     line: 'viewer_isolate(IfcWall)',                        family: 'Viewer' },
+  { verb: 'Paint',     line: 'viewer_colorize(IfcWall, "#d6ff3f")',            family: 'Viewer' },
+  { verb: 'Standardize', line: 'bsdd_property_sets("IfcWall")',                family: 'bSDD',      overlay: { kind: 'psets', psets: ['Pset_WallCommon', 'Qto_WallBaseQuantities', 'Pset_ConcreteElementGeneral'] } },
+  { verb: 'Add',       line: 'entity_create(IfcDoor)',                         family: 'Mutation' },
+  { verb: 'Section',   line: 'viewer_set_section(z = 2.2)',                    family: 'Viewer' },
+  { verb: 'Issue',     line: 'bcf_topic_create("missing fire rating")',        family: 'BCF',       overlay: { kind: 'pin', ref: 'BCF #04' } },
+  { verb: 'Inspect',   line: 'viewer_describe_selection()',                    family: 'Viewer',    overlay: { kind: 'card', ref: 'IfcWall #262', lines: ['Pset_WallCommon · IsExternal=true', 'FireRating=EI60 · 240 mm concrete'] } },
+];
+
+/** ms each step gets before advancing. */
+export const HERO_STEP_MS = 2000;
+
+interface Element {
+  mesh: THREE.Mesh;
+  baseColor: THREE.Color;
+  targetColor: THREE.Color;
+  baseOpacity: number;
+  targetOpacity: number;
+  /** Visible flag — used for the "new door" reveal. */
+  hidden?: boolean;
+  /** Multiplier for the mesh's stored Y so we can animate the new door sliding in. */
+  yOffset?: number;
+  baseY?: number;
+}
+
+export interface HeroSceneProps {
+  /** 0..HERO_STEPS.length-1 — drives material/camera/section animation. */
+  step: number;
+  className?: string;
+  /**
+   * Optional callback fired every animation frame with the current
+   * screen-space position of the BCF pin (relative to this element's
+   * top-left). Used by HeroOverlay to anchor the pin caption.
+   */
+  onPinFrame?: (frame: { x: number; y: number; visible: boolean } | null) => void;
+}
+
+export function HeroScene({ step, className, onPinFrame }: HeroSceneProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const sceneRef = useRef<SceneHandle | null>(null);
+  const onPinRef = useRef(onPinFrame);
+  onPinRef.current = onPinFrame;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const handle = createScene(container);
+    sceneRef.current = handle;
+
+    let raf = 0;
+    const tick = () => {
+      raf = requestAnimationFrame(tick);
+      onPinRef.current?.(handle.projectPin());
+    };
+    tick();
+    return () => {
+      cancelAnimationFrame(raf);
+      handle.dispose();
+      sceneRef.current = null;
+    };
+  }, []);
+
+  useEffect(() => {
+    sceneRef.current?.update(step);
+  }, [step]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className ?? 'relative aspect-[4/5] w-full overflow-hidden rounded-lg'}
+      style={{ background: '#0a0a0c' }}
+    />
+  );
+}
+
+// ── scene factory ──────────────────────────────────────────────────────────
+
+interface SceneHandle {
+  update(step: number): void;
+  dispose(): void;
+  /**
+   * Project the BCF pin's world position into the host element's local
+   * coordinate space so a sibling HTML overlay can track it through orbit
+   * and camera transitions. Returns null when the pin is behind the camera
+   * or the host has no size yet.
+   */
+  projectPin(): { x: number; y: number; visible: boolean } | null;
+}
+
+function createScene(container: HTMLElement): SceneHandle {
+  const allElements: Element[] = [];
+
+  // ── Renderer ─────────────────────────────────────────────────────────────
+  const renderer = new THREE.WebGLRenderer({
+    antialias: true,
+    alpha: true,
+    powerPreference: 'high-performance',
+  });
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  renderer.setSize(container.clientWidth, container.clientHeight, false);
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.setClearColor(NIGHT, 0);
+  renderer.localClippingEnabled = true;
+  container.appendChild(renderer.domElement);
+  renderer.domElement.style.display = 'block';
+  renderer.domElement.style.width = '100%';
+  renderer.domElement.style.height = '100%';
+
+  // ── Scene + camera ───────────────────────────────────────────────────────
+  const scene = new THREE.Scene();
+  scene.fog = new THREE.Fog(NIGHT, 18, 42);
+
+  const camera = new THREE.PerspectiveCamera(35, container.clientWidth / container.clientHeight, 0.1, 100);
+  camera.position.set(11, 8, 13);
+  camera.lookAt(0, 2.5, 0);
+
+  // ── Lighting ─────────────────────────────────────────────────────────────
+  scene.add(new THREE.HemisphereLight(0xb6c8ff, 0x1a1a22, 0.6));
+
+  const key = new THREE.DirectionalLight(0xffffff, 1.4);
+  key.position.set(8, 14, 6);
+  scene.add(key);
+
+  const rim = new THREE.DirectionalLight(0xff5cdc, 0.35);
+  rim.position.set(-10, 4, -8);
+  scene.add(rim);
+
+  const fill = new THREE.DirectionalLight(0xd6ff3f, 0.18);
+  fill.position.set(-4, 2, 8);
+  scene.add(fill);
+
+  // ── Ground ───────────────────────────────────────────────────────────────
+  const grid = new THREE.GridHelper(40, 40, 0x2a2a32, 0x16161c);
+  (grid.material as THREE.Material).transparent = true;
+  (grid.material as THREE.Material).opacity = 0.5;
+  grid.position.y = -0.02;
+  scene.add(grid);
+  const ground = new THREE.Mesh(
+    new THREE.CircleGeometry(20, 48),
+    new THREE.MeshStandardMaterial({ color: 0x0e0e12, roughness: 1 }),
+  );
+  ground.rotation.x = -Math.PI / 2;
+  ground.position.y = -0.03;
+  scene.add(ground);
+
+  // ── Building geometry ────────────────────────────────────────────────────
+  //
+  // Spatial conventions (model space, no parent rotation):
+  //   • +Z is the FRONT face — the one the default camera (in the +X/+Z
+  //     corner) looks at directly. Door + primary window wall live there.
+  //   • +X is the RIGHT face — the destination of the agent-created door
+  //     in step 8 (so the new entity is unmistakable on a wall that started
+  //     out blank).
+  //   • Camera auto-rotates around Y, so the back / left faces eventually
+  //     come around — we still populate them so the building looks right
+  //     from every angle.
+  const root = new THREE.Group();
+  scene.add(root);
+
+  const W = 8;            // building width  (X)
+  const D = 5;            // building depth  (Z)
+  const STOREY = 3;       // storey height
+  const WALL_THK = 0.18;
+  const FRONT_Z = D / 2 + 0.001;
+  const BACK_Z = -D / 2 - 0.001;
+  const RIGHT_X = W / 2 + 0.001;
+  const LEFT_X = -W / 2 - 0.001;
+
+  // Section plane (used by viewer_set_section step). Negative Y axis means
+  // we clip everything ABOVE the plane.
+  const sectionPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 100); // disabled by default (constant pushed far away)
+
+  function makeMesh(geom: THREE.BufferGeometry, hex: number): THREE.Mesh {
+    const mat = new THREE.MeshStandardMaterial({
+      color: new THREE.Color(hex),
+      metalness: 0.05,
+      roughness: 0.74,
+      clippingPlanes: [sectionPlane],
+      clipShadows: true,
+    });
+    return new THREE.Mesh(geom, mat);
+  }
+  function registerElement(mesh: THREE.Mesh, baseHex: number, baseOpacity = 1): Element {
+    const baseColor = new THREE.Color(baseHex);
+    const el: Element = {
+      mesh,
+      baseColor,
+      targetColor: baseColor.clone(),
+      baseOpacity,
+      targetOpacity: baseOpacity,
+      baseY: mesh.position.y,
+      yOffset: 0,
+    };
+    allElements.push(el);
+    return el;
+  }
+
+  // Slab
+  const slab = makeMesh(new THREE.BoxGeometry(W + 0.4, 0.18, D + 0.4), PAPER_DIM);
+  slab.position.y = -0.09;
+  root.add(slab);
+  const slabEl = registerElement(slab, PAPER_DIM);
+
+  // Walls per storey. The two camera-facing walls (FRONT + RIGHT) are
+  // tagged "outer" so the color_by_property step splits visibly; BACK +
+  // LEFT play "inner". Each face is one solid box — windows + doors sit
+  // *on top of* the wall as separate meshes (we’re showing IFC entities,
+  // not boolean cuts, so the layered geometry reads better).
+  const wallsByStorey: Element[][] = [[], []];
+  const externalByStorey: { outer: Element[]; inner: Element[] }[] = [
+    { outer: [], inner: [] },
+    { outer: [], inner: [] },
+  ];
+  const windowsByStorey: Element[][] = [[], []];
+  const doorEls: Element[] = [];
+
+  for (let storey = 0; storey < 2; storey++) {
+    const yMid = storey * STOREY + (STOREY - 0.05) / 2 + 0.05;
+    const wallFront = makeMesh(new THREE.BoxGeometry(W, STOREY - 0.05, WALL_THK), 0x6c6c75);
+    wallFront.position.set(0, yMid, D / 2);
+    const wallBack = makeMesh(new THREE.BoxGeometry(W, STOREY - 0.05, WALL_THK), 0x6c6c75);
+    wallBack.position.set(0, yMid, -D / 2);
+    const wallRight = makeMesh(new THREE.BoxGeometry(WALL_THK, STOREY - 0.05, D), 0x6c6c75);
+    wallRight.position.set(W / 2, yMid, 0);
+    const wallLeft = makeMesh(new THREE.BoxGeometry(WALL_THK, STOREY - 0.05, D), 0x6c6c75);
+    wallLeft.position.set(-W / 2, yMid, 0);
+    [wallFront, wallBack, wallRight, wallLeft].forEach((m) => root.add(m));
+
+    const elFront = registerElement(wallFront, 0x6c6c75);
+    const elBack = registerElement(wallBack, 0x6c6c75);
+    const elRight = registerElement(wallRight, 0x6c6c75);
+    const elLeft = registerElement(wallLeft, 0x6c6c75);
+    wallsByStorey[storey].push(elFront, elBack, elRight, elLeft);
+    externalByStorey[storey].outer.push(elFront, elRight);
+    externalByStorey[storey].inner.push(elBack, elLeft);
+
+    // FRONT-face windows. Storey 0 has 2 windows flanking the centre door;
+    // storey 1 has 3 evenly spaced (no door above to dodge). Generous
+    // spacing so nothing overlaps even at WALL_THK + offsets.
+    const winY = yMid + 0.55; // sill ~yMid+0.05, head ~yMid+1.05
+    const frontXs = storey === 0 ? [-3.2, +3.2] : [-3.2, 0, +3.2];
+    for (const x of frontXs) {
+      const win = makeMesh(new THREE.BoxGeometry(1.0, 1.1, WALL_THK + 0.02), 0x2c3a52);
+      win.position.set(x, winY, FRONT_Z);
+      root.add(win);
+      windowsByStorey[storey].push(registerElement(win, 0x2c3a52));
+    }
+
+    // BACK-face windows: 3 per storey, evenly spaced (visible while the
+    // camera auto-orbits past the rear).
+    for (const x of [-3.2, 0, +3.2]) {
+      const win = makeMesh(new THREE.BoxGeometry(1.0, 1.1, WALL_THK + 0.02), 0x2c3a52);
+      win.position.set(x, winY, BACK_Z);
+      root.add(win);
+      windowsByStorey[storey].push(registerElement(win, 0x2c3a52));
+    }
+
+    // SIDE-face windows: 1 per storey on the LEFT face only — the RIGHT
+    // face is reserved for the agent-created side door (step 8).
+    const winSide = makeMesh(new THREE.BoxGeometry(WALL_THK + 0.02, 1.1, 1.0), 0x2c3a52);
+    winSide.position.set(LEFT_X, winY, 0);
+    root.add(winSide);
+    windowsByStorey[storey].push(registerElement(winSide, 0x2c3a52));
+  }
+
+  // ORIGINAL door — front face, ground floor, dead-centre on the wall. The
+  // door is taller than the windows above it, so the silhouette reads as
+  // a real entrance rather than another opening.
+  const door = makeMesh(new THREE.BoxGeometry(1.05, 2.2, WALL_THK + 0.04), 0x2a2a30);
+  door.position.set(0, 1.1, FRONT_Z);
+  root.add(door);
+  doorEls.push(registerElement(door, 0x2a2a30));
+
+  // Tiny "step" / threshold under the door so it visibly sits on the slab.
+  const threshold = makeMesh(new THREE.BoxGeometry(1.4, 0.05, 0.5), 0x55554f);
+  threshold.position.set(0, 0.025, FRONT_Z + 0.18);
+  root.add(threshold);
+  registerElement(threshold, 0x55554f);
+
+  // NEW door — created by entity_create step. Lives on the RIGHT face (a
+  // wall that started out blank), centred on Z. Hidden + lifted high by
+  // default; slides down + fades in when the agent fires entity_create so
+  // the addition is unmistakable.
+  const newDoor = makeMesh(new THREE.BoxGeometry(WALL_THK + 0.04, 2.2, 1.05), NEW_DOOR_HUE);
+  newDoor.position.set(RIGHT_X, 4.6, 0);
+  root.add(newDoor);
+  const newDoorEl = registerElement(newDoor, NEW_DOOR_HUE, 0);
+  newDoorEl.hidden = true;
+  // Threshold for the new door — also hidden until the agent acts.
+  const newThreshold = makeMesh(new THREE.BoxGeometry(0.5, 0.05, 1.4), 0x55554f);
+  newThreshold.position.set(RIGHT_X + 0.18, 0.025, 0);
+  root.add(newThreshold);
+  const newThresholdEl = registerElement(newThreshold, 0x55554f, 0);
+  newThresholdEl.hidden = true;
+
+  // Storey-2 floor (so the silhouette reads as two-storey).
+  const floor2 = makeMesh(new THREE.BoxGeometry(W + 0.05, 0.08, D + 0.05), PAPER_DIM);
+  floor2.position.y = STOREY;
+  root.add(floor2);
+  const floor2El = registerElement(floor2, PAPER_DIM);
+
+  // Roof — true hip roof matching the 8 × 5 footprint with a small eave
+  // overhang. Built as a closed mesh of two trapezoids (front/back) + two
+  // triangles (left/right) meeting at a ridge along the long X axis.
+  const roof = makeMesh(makeHipRoof(W, D, 1.5, 0.5), 0x4a4a52);
+  roof.position.y = 2 * STOREY + 0.05;
+  root.add(roof);
+  const roofEl = registerElement(roof, 0x4a4a52);
+
+  // Eave board — a thin lip along the top edge of the upper walls so the
+  // roof meets the walls cleanly instead of floating.
+  const eave = makeMesh(new THREE.BoxGeometry(W + 1.0, 0.08, D + 1.0), 0x3e3e44);
+  eave.position.y = 2 * STOREY + 0.04;
+  root.add(eave);
+  registerElement(eave, 0x3e3e44);
+
+  // ── Section plane visualisation ─────────────────────────────────────────
+  // A faint chartreuse rectangle that snaps in only when the section step
+  // fires, so the user sees WHERE the cut is happening.
+  const sectionVis = new THREE.Mesh(
+    new THREE.PlaneGeometry(W + 1.2, D + 1.2),
+    new THREE.MeshBasicMaterial({
+      color: ACCENT,
+      side: THREE.DoubleSide,
+      transparent: true,
+      opacity: 0,
+      depthWrite: false,
+    }),
+  );
+  sectionVis.rotation.x = -Math.PI / 2;
+  sectionVis.position.y = 2.2;
+  scene.add(sectionVis);
+
+  // ── BCF pin (3D Sprite) ─────────────────────────────────────────────────
+  // A small canvas-baked red disc that lives in world space on the front
+  // wall, top-right area. Sprites always face the camera, so this stays
+  // legible through auto-rotate. The "BCF #04" caption next to it is still
+  // an HTML overlay (handled by McpLanding) but it now anchors to the
+  // sprite’s projected screen position via getProjectedPin().
+  const pinCanvas = document.createElement('canvas');
+  pinCanvas.width = 96;
+  pinCanvas.height = 96;
+  const pinCtx = pinCanvas.getContext('2d');
+  if (pinCtx) {
+    // soft glow
+    const grad = pinCtx.createRadialGradient(48, 48, 6, 48, 48, 48);
+    grad.addColorStop(0, 'rgba(255, 58, 58, 0.55)');
+    grad.addColorStop(0.55, 'rgba(255, 58, 58, 0.18)');
+    grad.addColorStop(1, 'rgba(255, 58, 58, 0)');
+    pinCtx.fillStyle = grad;
+    pinCtx.fillRect(0, 0, 96, 96);
+    // solid disc
+    pinCtx.beginPath();
+    pinCtx.arc(48, 48, 22, 0, Math.PI * 2);
+    pinCtx.fillStyle = '#ff3a3a';
+    pinCtx.fill();
+    pinCtx.lineWidth = 2;
+    pinCtx.strokeStyle = '#fff';
+    pinCtx.stroke();
+    // "!" glyph
+    pinCtx.fillStyle = '#fff';
+    pinCtx.font = 'bold 30px ui-monospace, "JetBrains Mono", Menlo, monospace';
+    pinCtx.textAlign = 'center';
+    pinCtx.textBaseline = 'middle';
+    pinCtx.fillText('!', 48, 49);
+  }
+  const pinTex = new THREE.CanvasTexture(pinCanvas);
+  pinTex.colorSpace = THREE.SRGBColorSpace;
+  const pinMat = new THREE.SpriteMaterial({
+    map: pinTex,
+    transparent: true,
+    opacity: 0,
+    depthTest: false,
+  });
+  const pin = new THREE.Sprite(pinMat);
+  pin.scale.set(0.9, 0.9, 1);
+  // Anchor on the front wall, towards the right side (away from the door).
+  // World coords map directly to model since root has no rotation.
+  pin.position.set(2.6, 1.9, FRONT_Z + 0.1);
+  scene.add(pin);
+  let pinOpacityTarget = 0;
+
+  // ── Controls ─────────────────────────────────────────────────────────────
+  const controls = new OrbitControls(camera, renderer.domElement);
+  controls.target.set(0, STOREY, 0);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.08;
+  controls.enablePan = false;
+  controls.enableZoom = false;
+  controls.minPolarAngle = Math.PI / 4;
+  controls.maxPolarAngle = Math.PI / 2.05;
+  controls.autoRotate = true;
+  controls.autoRotateSpeed = 0.45;
+
+  let resumeTimer: ReturnType<typeof setTimeout> | null = null;
+  controls.addEventListener('start', () => {
+    controls.autoRotate = false;
+    if (resumeTimer) clearTimeout(resumeTimer);
+  });
+  controls.addEventListener('end', () => {
+    if (resumeTimer) clearTimeout(resumeTimer);
+    resumeTimer = setTimeout(() => { controls.autoRotate = true; }, 2200);
+  });
+
+  // ── Resize ───────────────────────────────────────────────────────────────
+  const ro = new ResizeObserver(() => {
+    const w = container.clientWidth;
+    const h = container.clientHeight;
+    if (w === 0 || h === 0) return;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h, false);
+  });
+  ro.observe(container);
+
+  // ── Camera tween targets ─────────────────────────────────────────────────
+  // No parent rotation any more, so all targets read in plain world coords.
+  // Default: front-right corner at slight elevation.
+  // Close:   nudged in toward the front face for the describe-selection step.
+  // RightAngle: looks at the +X (RIGHT) face where the new door appears,
+  //             rotated camera around to the side so it’s visible.
+  const cameraDefault = new THREE.Vector3(12, 8, 13);
+  const cameraClose = new THREE.Vector3(8, 5.5, 10);
+  const cameraRightAngle = new THREE.Vector3(14, 6, 6);
+  let cameraTarget = cameraDefault.clone();
+
+  // Section plane state — animates between "off" (constant 100) and "on"
+  // (constant 2.2 → clipping above y=2.2).
+  let sectionConstantTarget = 100;
+  let sectionVisOpacityTarget = 0;
+
+  // ── Animation loop ───────────────────────────────────────────────────────
+  let raf = 0;
+  let disposed = false;
+  function tick() {
+    if (disposed) return;
+    raf = requestAnimationFrame(tick);
+    controls.update();
+
+    for (const el of allElements) {
+      const mat = el.mesh.material as THREE.MeshStandardMaterial;
+      mat.color.lerp(el.targetColor, 0.07);
+      const targetOpacity = el.hidden ? 0 : el.targetOpacity;
+      mat.opacity = THREE.MathUtils.lerp(mat.opacity, targetOpacity, 0.07);
+      mat.transparent = mat.opacity < 0.999;
+      // Optional Y slide (used for the new-door reveal)
+      if (el.baseY !== undefined && el.yOffset !== undefined) {
+        const targetY = el.baseY + el.yOffset;
+        el.mesh.position.y = THREE.MathUtils.lerp(el.mesh.position.y, targetY, 0.08);
+      }
+    }
+
+    // Section plane tween
+    sectionPlane.constant = THREE.MathUtils.lerp(sectionPlane.constant, sectionConstantTarget, 0.08);
+    const sectMat = sectionVis.material as THREE.MeshBasicMaterial;
+    sectMat.opacity = THREE.MathUtils.lerp(sectMat.opacity, sectionVisOpacityTarget, 0.1);
+
+    // BCF pin sprite tween
+    pinMat.opacity = THREE.MathUtils.lerp(pinMat.opacity, pinOpacityTarget, 0.12);
+
+    camera.position.lerp(cameraTarget, 0.04);
+    renderer.render(scene, camera);
+  }
+  tick();
+
+  // ── State controller ────────────────────────────────────────────────────
+  // Every step is its own switch case so each transition is a *complete*
+  // scene description, not a cumulative diff. That's what makes the visual
+  // story arc legible — Survey paints types, Layer overrides with storeys,
+  // Standardize pulls everything into bSDD blue, etc. The few things that
+  // genuinely persist across steps (the agent-created door once it lands;
+  // the section plane while it’s active) are restored explicitly inside
+  // each case that needs them.
+  function setTarget(el: Element, color: number, opacity = 1) {
+    el.targetColor.setHex(color);
+    el.targetOpacity = opacity;
+    el.hidden = false;
+  }
+  function dim(el: Element, opacity = 0.16) {
+    el.targetOpacity = opacity;
+  }
+  function reset() {
+    for (const el of allElements) {
+      el.targetColor.copy(el.baseColor);
+      el.targetOpacity = el.baseOpacity;
+      if (el.baseY !== undefined) el.yOffset = 0;
+    }
+    cameraTarget = cameraDefault.clone();
+    sectionConstantTarget = 100;
+    sectionVisOpacityTarget = 0;
+    newDoorEl.hidden = true;
+    newThresholdEl.hidden = true;
+    pinOpacityTarget = 0;
+  }
+
+  // After step 8, the new door / threshold persist into later steps. This
+  // helper re-applies that state inside cases that come after entity_create.
+  function keepNewDoor() {
+    newDoorEl.hidden = false;
+    newDoorEl.targetOpacity = 1;
+    newDoorEl.targetColor.setHex(NEW_DOOR_HUE);
+    newDoorEl.yOffset = -3.5;
+    newThresholdEl.hidden = false;
+    newThresholdEl.targetOpacity = 1;
+  }
+
+  // Type aliases for legibility inside the switch
+  const allWalls = () => [...wallsByStorey[0], ...wallsByStorey[1]];
+  const allWindows = () => [...windowsByStorey[0], ...windowsByStorey[1]];
+
+  function update(step: number) {
+    reset();
+    switch (step) {
+      // ── 00  OPEN  ───────────────────────────────────────────────────────
+      // Establish neutral framing — camera sits in the front-right corner
+      // and slowly orbits.
+      case 0: {
+        cameraTarget = cameraDefault.clone();
+        break;
+      }
+
+      // ── 01  AUDIT  ──────────────────────────────────────────────────────
+      // model_audit reports a single offending wall (missing FireRating).
+      // Visual: the offending wall flashes a saturated red while the rest
+      // of the building stays neutral.
+      case 1: {
+        const issueWall = externalByStorey[0].outer[0]; // front-face ground wall
+        setTarget(issueWall, 0xff3a3a);
+        cameraTarget = new THREE.Vector3(13, 8.5, 14);
+        break;
+      }
+
+      // ── 02  SURVEY  ─────────────────────────────────────────────────────
+      // count_entities groups by type. Visual: each type takes its own
+      // distinct hue at the same time so the histogram in the overlay
+      // maps onto the building. Pulls camera up so slabs + roof read.
+      case 2: {
+        for (const el of allWalls()) setTarget(el, 0x73daca);          // walls — teal
+        for (const el of allWindows()) setTarget(el, 0x7aa2f7);        // windows — blue
+        for (const el of doorEls) setTarget(el, 0xff9e64);             // doors — orange
+        setTarget(slabEl, 0xbb9af7);                                   // slabs — purple
+        setTarget(floor2El, 0xbb9af7);
+        setTarget(roofEl, 0xc8c8d0);                                   // roof — pale
+        cameraTarget = new THREE.Vector3(11, 11, 13);
+        break;
+      }
+
+      // ── 03  LAYER  ──────────────────────────────────────────────────────
+      // viewer_color_by_storey — ground floor cool blue, upper warm orange.
+      case 3: {
+        for (const el of wallsByStorey[0]) setTarget(el, STOREY_HUE_LO);
+        for (const el of wallsByStorey[1]) setTarget(el, STOREY_HUE_HI);
+        cameraTarget = cameraDefault.clone();
+        break;
+      }
+
+      // ── 04  CLASSIFY  ───────────────────────────────────────────────────
+      // viewer_color_by_property("IsExternal") — outer (front + right)
+      // walls go chartreuse, inner walls go cool lavender.
+      case 4: {
+        for (const s of [0, 1]) {
+          for (const el of externalByStorey[s].outer) setTarget(el, PROP_TRUE);
+          for (const el of externalByStorey[s].inner) setTarget(el, PROP_FALSE);
+        }
+        cameraTarget = new THREE.Vector3(13, 7, 11);
+        break;
+      }
+
+      // ── 05  FOCUS  ──────────────────────────────────────────────────────
+      // viewer_isolate — pick ONE specific wall (front face, ground storey
+      // — the wall the door sits on) and dim absolutely everything else
+      // to ~2 %. Camera dollies in close to a near-elevation view so the
+      // single wall reads at full size.
+      case 5: {
+        const pickedWall = wallsByStorey[0][0]; // FRONT, storey 0
+        for (const el of allElements) {
+          if (el === pickedWall) continue;
+          el.targetOpacity = 0.02;
+        }
+        setTarget(pickedWall, 0x6c6c75); // neutral grey — Paint step pops next
+        cameraTarget = new THREE.Vector3(4, 3.5, 10);
+        break;
+      }
+
+      // ── 06  PAINT  ──────────────────────────────────────────────────────
+      // viewer_colorize per-entity — every visible IFC element gets a
+      // distinct hue from the palette. The agent fanning out colours per
+      // entity makes the "we touched everything" point loud + clear.
+      case 6: {
+        // Bring everything back from Focus first.
+        for (const el of allElements) {
+          el.targetOpacity = el.baseOpacity;
+        }
+        // Newly-created door doesn’t exist yet — keep it hidden until step 8.
+        newDoorEl.hidden = true;
+        newThresholdEl.hidden = true;
+
+        // Group + walk the palette. Each group cycles independently so
+        // we don’t end up with two adjacent walls in the same colour.
+        const RAINBOW = [
+          0xff3a3a, 0xff9e64, 0xe0af68, 0xd6ff3f,
+          0x9ece6a, 0x73daca, 0x7aa2f7, 0xbb9af7, 0xff5cdc,
+        ];
+        let i = 0;
+        for (const el of allWalls()) setTarget(el, RAINBOW[i++ % RAINBOW.length]);
+        for (const el of allWindows()) setTarget(el, RAINBOW[i++ % RAINBOW.length]);
+        for (const el of doorEls) setTarget(el, RAINBOW[i++ % RAINBOW.length]);
+        setTarget(slabEl, RAINBOW[i++ % RAINBOW.length]);
+        setTarget(floor2El, RAINBOW[i++ % RAINBOW.length]);
+        setTarget(roofEl, RAINBOW[i++ % RAINBOW.length]);
+        cameraTarget = new THREE.Vector3(11, 7, 12);
+        break;
+      }
+
+      // ── 07  STANDARDIZE  (bSDD) ────────────────────────────────────────
+      // bsdd_property_sets — walls take the deep "schema blue" cue, still
+      // isolated, with the data sheet overlay showing the canonical Pset.
+      case 7: {
+        dim(roofEl, 0.0);
+        dim(slabEl, 0.04);
+        dim(floor2El, 0.04);
+        for (const el of allWindows()) dim(el, 0.02);
+        for (const el of doorEls) dim(el, 0.02);
+        for (const el of allWalls()) setTarget(el, 0x2e5fc7);
+        cameraTarget = new THREE.Vector3(9, 5, 10);
+        break;
+      }
+
+      // ── 08  ADD  ────────────────────────────────────────────────────────
+      // entity_create(IfcDoor) — reveal the new door on the +X face,
+      // restore non-wall opacities so the building reads in context, swing
+      // the camera over so the addition is unmistakable.
+      case 8: {
+        for (const el of allWindows()) {
+          el.targetOpacity = 1;
+          el.targetColor.setHex(0x2c3a52);
+        }
+        for (const el of doorEls) {
+          el.targetOpacity = 1;
+          el.targetColor.setHex(0x2a2a30);
+        }
+        slabEl.targetOpacity = 1;
+        floor2El.targetOpacity = 1;
+        roofEl.targetOpacity = 1;
+        for (const el of allWalls()) {
+          el.targetOpacity = 1;
+          el.targetColor.setHex(0x6c6c75);
+        }
+        keepNewDoor();
+        cameraTarget = cameraRightAngle.clone();
+        break;
+      }
+
+      // ── 09  SECTION  ────────────────────────────────────────────────────
+      // viewer_set_section(z=2.2) — clip the upper storey progressively;
+      // a chartreuse plane rectangle marks where the cut is. Camera drops
+      // low so the section reads as a horizontal slice.
+      case 9: {
+        keepNewDoor();
+        sectionConstantTarget = 2.2;
+        sectionVisOpacityTarget = 0.22;
+        cameraTarget = new THREE.Vector3(10, 4, 12);
+        break;
+      }
+
+      // ── 10  ISSUE  (BCF)  ──────────────────────────────────────────────
+      // bcf_topic_create — the 3D pin sprite (anchored to the front wall
+      // top-right) fades in. The wall the pin sits on flashes red so the
+      // anchor is unambiguous. Section stays clipped to keep the lower
+      // storey reading.
+      case 10: {
+        keepNewDoor();
+        sectionConstantTarget = 2.2;
+        sectionVisOpacityTarget = 0.14;
+        const issueWall = externalByStorey[0].outer[0]; // FRONT wall
+        for (const el of allWalls()) dim(el, 0.45);
+        setTarget(issueWall, 0xff3a3a, 1);
+        pinOpacityTarget = 1;
+        cameraTarget = new THREE.Vector3(9.5, 4, 10);
+        break;
+      }
+
+      // ── 11  INSPECT  ────────────────────────────────────────────────────
+      // viewer_describe_selection — clear section, dim the building down,
+      // light up the picked wall in magenta. The describe-card overlay
+      // does the rest.
+      case 11: {
+        keepNewDoor();
+        sectionConstantTarget = 100;
+        sectionVisOpacityTarget = 0;
+        const pickedEl = externalByStorey[0].outer[0];
+        for (const el of allWalls()) dim(el, 0.18);
+        for (const el of allWindows()) dim(el, 0.5);
+        setTarget(pickedEl, ACCENT_2, 1);
+        cameraTarget = cameraClose.clone();
+        break;
+      }
+
+      default: {
+        cameraTarget = cameraDefault.clone();
+      }
+    }
+  }
+
+  update(0);
+
+  // Re-usable scratch vector to avoid alloc churn in projectPin().
+  const projScratch = new THREE.Vector3();
+
+  return {
+    update,
+    projectPin() {
+      const w = container.clientWidth;
+      const h = container.clientHeight;
+      if (w === 0 || h === 0) return null;
+      projScratch.copy(pin.position).project(camera);
+      const visible = projScratch.z >= -1 && projScratch.z <= 1;
+      return {
+        x: ((projScratch.x + 1) / 2) * w,
+        y: ((-projScratch.y + 1) / 2) * h,
+        visible,
+      };
+    },
+    dispose() {
+      disposed = true;
+      cancelAnimationFrame(raf);
+      ro.disconnect();
+      controls.dispose();
+      if (resumeTimer) clearTimeout(resumeTimer);
+      scene.traverse((obj) => {
+        const mesh = obj as THREE.Mesh;
+        if (mesh.geometry) mesh.geometry.dispose();
+        const mat = mesh.material as THREE.Material | THREE.Material[] | undefined;
+        if (Array.isArray(mat)) mat.forEach((m) => m.dispose());
+        else if (mat) mat.dispose();
+      });
+      // The pin sprite uses a CanvasTexture allocated outside the
+      // material-walk above (the sprite material's `map` is set, but
+      // scene.traverse only disposes materials & geometries). Drop it
+      // explicitly so the canvas-backed GPU texture doesn't leak across
+      // mount/unmount cycles.
+      pinTex.dispose();
+      renderer.dispose();
+      if (renderer.domElement.parentNode === container) {
+        container.removeChild(renderer.domElement);
+      }
+    },
+  };
+}
+
+// ── geometry helpers ──────────────────────────────────────────────────────
+
+/**
+ * Build a hip-roof BufferGeometry for a rectangular footprint W × D with a
+ * given peak `height` and `overhang` past the eaves. The ridge runs along
+ * the long axis (X). All faces are non-indexed so per-face normals shade
+ * cleanly without averaging across the ridge.
+ */
+function makeHipRoof(W: number, D: number, height: number, overhang: number): THREE.BufferGeometry {
+  const hx = W / 2 + overhang;
+  const hz = D / 2 + overhang;
+  // 45° hips on the short ends → the ridge is hz inset from each X edge.
+  const ridgeX = Math.max(0, hx - hz);
+
+  // Eave corners (y = 0) and the two ridge endpoints (y = height).
+  const FL: [number, number, number] = [-hx, 0, hz];   // front-left
+  const FR: [number, number, number] = [hx, 0, hz];    // front-right
+  const BR: [number, number, number] = [hx, 0, -hz];   // back-right
+  const BL: [number, number, number] = [-hx, 0, -hz];  // back-left
+  const RL: [number, number, number] = [-ridgeX, height, 0]; // ridge-left
+  const RR: [number, number, number] = [ridgeX, height, 0];  // ridge-right
+
+  const positions: number[] = [];
+  function tri(a: [number, number, number], b: [number, number, number], c: [number, number, number]) {
+    positions.push(...a, ...b, ...c);
+  }
+  function quad(a: [number, number, number], b: [number, number, number], c: [number, number, number], d: [number, number, number]) {
+    tri(a, b, c);
+    tri(a, c, d);
+  }
+
+  // Vertex order is CCW when viewed from outside the roof. Three.js will
+  // recompute normals after we set positions.
+  // Front (looking from +Z): FL → FR → RR → RL
+  quad(FL, FR, RR, RL);
+  // Right end (looking from +X): FR → BR → RR (triangle)
+  tri(FR, BR, RR);
+  // Back (looking from -Z): BR → BL → RL → RR
+  quad(BR, BL, RL, RR);
+  // Left end (looking from -X): BL → FL → RL (triangle)
+  tri(BL, FL, RL);
+
+  const geom = new THREE.BufferGeometry();
+  geom.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geom.computeVertexNormals();
+  return geom;
+}