@ifc-lite/viewer 1.17.3 → 1.17.6

package/src/components/viewer/tools/SectionCapControls.tsx

@@ -0,0 +1,237 @@
+/* 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/. */
+
+/**
+ * Cap-surface appearance controls shown inside the expanded Section panel.
+ *
+ * Layout principle (tight compact panel, ≤ 260 px wide):
+ *   [Display]          Surfaces ⬛   Lines ⬛
+ *   ───────────────────────────────────────────────
+ *   [Hatch]            <pattern select>
+ *   [Colours]          Fill ▣   Hatch ▣
+ *   [Shape]            Spacing __px  Angle __°  Width __px
+ *
+ * Surfaces and Lines toggle independently so users can get a clean
+ * "architectural drawing" look (outlines only), a pure hatched fill, or
+ * the combination. All style inputs are hidden when Surfaces is off.
+ */
+
+import { useCallback, useId } from 'react';
+import { useViewerStore } from '@/store';
+import type { SectionCapHatchId } from '@/store/types';
+
+const PATTERN_LABELS: Record<SectionCapHatchId, string> = {
+  solid:      'Solid fill',
+  diagonal:   'Diagonal',
+  crossHatch: 'Cross-hatch',
+  horizontal: 'Horizontal',
+  vertical:   'Vertical',
+  concrete:   'Concrete',
+  brick:      'Brick',
+  insulation: 'Insulation',
+};
+
+const PATTERN_IDS: SectionCapHatchId[] = [
+  'diagonal', 'crossHatch', 'horizontal', 'vertical',
+  'concrete', 'brick', 'insulation', 'solid',
+];
+
+function rgbaToHex(c: [number, number, number, number]): string {
+  const to2 = (v: number) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, '0');
+  return `#${to2(c[0])}${to2(c[1])}${to2(c[2])}`;
+}
+
+function hexToRgba(hex: string, alpha: number): [number, number, number, number] {
+  const m = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  if (!m) return [1, 1, 1, alpha];
+  return [
+    parseInt(m[1], 16) / 255,
+    parseInt(m[2], 16) / 255,
+    parseInt(m[3], 16) / 255,
+    alpha,
+  ];
+}
+
+interface DisplayToggleProps {
+  active: boolean;
+  label: string;
+  onToggle: () => void;
+}
+
+function DisplayToggle({ active, label, onToggle }: DisplayToggleProps): React.JSX.Element {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-pressed={active}
+      className={`flex items-center justify-center gap-1.5 px-2 py-1 text-[10px] font-mono uppercase tracking-wide border rounded transition-colors ${
+        active
+          ? 'bg-primary text-primary-foreground border-primary'
+          : 'bg-muted text-muted-foreground border-muted hover:border-foreground/20'
+      }`}
+      title={`${active ? 'Hide' : 'Show'} ${label.toLowerCase()}`}
+    >
+      <span
+        aria-hidden
+        className={`inline-block h-1.5 w-1.5 rounded-full ${active ? 'bg-primary-foreground' : 'bg-muted-foreground'}`}
+      />
+      {label}
+    </button>
+  );
+}
+
+export function SectionCapControls(): React.JSX.Element {
+  const sectionPlane       = useViewerStore((s) => s.sectionPlane);
+  const setShowCap         = useViewerStore((s) => s.setSectionShowCap);
+  const setShowOutlines    = useViewerStore((s) => s.setSectionShowOutlines);
+  const setCapStyle        = useViewerStore((s) => s.setSectionCapStyle);
+
+  const onPattern = useCallback((e: React.ChangeEvent<HTMLSelectElement>) => {
+    setCapStyle({ pattern: e.target.value as SectionCapHatchId });
+  }, [setCapStyle]);
+
+  const onFillColor = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setCapStyle({ fillColor: hexToRgba(e.target.value, sectionPlane.capStyle.fillColor[3]) });
+  }, [setCapStyle, sectionPlane.capStyle.fillColor]);
+
+  const onStrokeColor = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setCapStyle({ strokeColor: hexToRgba(e.target.value, sectionPlane.capStyle.strokeColor[3]) });
+  }, [setCapStyle, sectionPlane.capStyle.strokeColor]);
+
+  const onSpacing = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const v = Number(e.target.value);
+    if (Number.isFinite(v)) setCapStyle({ spacingPx: Math.max(2, v) });
+  }, [setCapStyle]);
+
+  const onAngle = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const deg = Number(e.target.value);
+    if (Number.isFinite(deg)) setCapStyle({ angleRad: (deg * Math.PI) / 180 });
+  }, [setCapStyle]);
+
+  const onWidth = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const v = Number(e.target.value);
+    if (Number.isFinite(v)) setCapStyle({ widthPx: Math.max(1, v) });
+  }, [setCapStyle]);
+
+  const onToggleCap      = useCallback(() => setShowCap(!sectionPlane.showCap), [setShowCap, sectionPlane.showCap]);
+  const onToggleOutlines = useCallback(() => setShowOutlines(!sectionPlane.showOutlines), [setShowOutlines, sectionPlane.showOutlines]);
+
+  const angleDeg = Math.round((sectionPlane.capStyle.angleRad * 180) / Math.PI);
+
+  // Stable ids for label/control association. Multiple instances of the
+  // panel (rare, but possible during HMR) each get their own id namespace.
+  const baseId = useId();
+  const patternId = `${baseId}-pattern`;
+  const fillId    = `${baseId}-fill`;
+  const strokeId  = `${baseId}-stroke`;
+  const spacingId = `${baseId}-spacing`;
+  const angleId   = `${baseId}-angle`;
+  const widthId   = `${baseId}-width`;
+
+  const hatchInputsDisabled = !sectionPlane.showCap;
+
+  return (
+    <div className="mt-3 border-t pt-3 space-y-3">
+      {/* Display toggles — surfaces and lines independently. */}
+      <div>
+        <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-1.5">Display</div>
+        <div className="grid grid-cols-2 gap-2">
+          <DisplayToggle active={sectionPlane.showCap}      label="Surfaces" onToggle={onToggleCap} />
+          <DisplayToggle active={sectionPlane.showOutlines} label="Lines"    onToggle={onToggleOutlines} />
+        </div>
+      </div>
+
+      {/* Hatch style — disabled visually when surfaces are off. */}
+      <fieldset
+        disabled={hatchInputsDisabled}
+        className={`space-y-2 ${hatchInputsDisabled ? 'opacity-50 pointer-events-none' : ''}`}
+      >
+        <div>
+          <label htmlFor={patternId} className="text-[10px] uppercase tracking-wider text-muted-foreground block mb-1">
+            Hatch pattern
+          </label>
+          <select
+            id={patternId}
+            value={sectionPlane.capStyle.pattern}
+            onChange={onPattern}
+            className="w-full text-xs bg-muted px-2 py-1.5 rounded border-none"
+          >
+            {PATTERN_IDS.map((id) => (
+              <option key={id} value={id}>{PATTERN_LABELS[id]}</option>
+            ))}
+          </select>
+        </div>
+
+        <div className="grid grid-cols-2 gap-2">
+          <label htmlFor={fillId} className="flex items-center gap-2 text-[10px] uppercase tracking-wider text-muted-foreground">
+            <input
+              id={fillId}
+              type="color"
+              value={rgbaToHex(sectionPlane.capStyle.fillColor)}
+              onChange={onFillColor}
+              className="h-5 w-5 rounded cursor-pointer border border-muted"
+              aria-label="Fill colour"
+            />
+            Fill
+          </label>
+          <label htmlFor={strokeId} className="flex items-center gap-2 text-[10px] uppercase tracking-wider text-muted-foreground">
+            <input
+              id={strokeId}
+              type="color"
+              value={rgbaToHex(sectionPlane.capStyle.strokeColor)}
+              onChange={onStrokeColor}
+              className="h-5 w-5 rounded cursor-pointer border border-muted"
+              aria-label="Hatch colour"
+            />
+            Hatch
+          </label>
+        </div>
+
+        <div className="grid grid-cols-3 gap-2">
+          <div>
+            <label htmlFor={spacingId} className="text-[10px] text-muted-foreground block mb-1">Spacing (px)</label>
+            <input
+              id={spacingId}
+              type="number"
+              min="2"
+              max="64"
+              step="1"
+              value={sectionPlane.capStyle.spacingPx}
+              onChange={onSpacing}
+              className="w-full text-xs bg-muted px-1.5 py-0.5 rounded border-none text-right"
+            />
+          </div>
+          <div>
+            <label htmlFor={angleId} className="text-[10px] text-muted-foreground block mb-1">Angle (°)</label>
+            <input
+              id={angleId}
+              type="number"
+              min="-180"
+              max="180"
+              step="5"
+              value={angleDeg}
+              onChange={onAngle}
+              className="w-full text-xs bg-muted px-1.5 py-0.5 rounded border-none text-right"
+            />
+          </div>
+          <div>
+            <label htmlFor={widthId} className="text-[10px] text-muted-foreground block mb-1">Width (px)</label>
+            <input
+              id={widthId}
+              type="number"
+              min="1"
+              max="16"
+              step="0.5"
+              value={sectionPlane.capStyle.widthPx}
+              onChange={onWidth}
+              className="w-full text-xs bg-muted px-1.5 py-0.5 rounded border-none text-right"
+            />
+          </div>
+        </div>
+      </fieldset>
+    </div>
+  );
+}
+
+export default SectionCapControls;

package/src/components/viewer/tools/SectionPanel.tsx

@@ -7,17 +7,19 @@
  */
 
 import React, { useCallback, useState } from 'react';
-import { X, Slice, ChevronDown, FileImage } from 'lucide-react';
+import { X, Slice, ChevronDown, FileImage, FlipHorizontal2 } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { useViewerStore } from '@/store';
 import { AXIS_INFO } from './sectionConstants';
 import { SectionPlaneVisualization } from './SectionVisualization';
+import { SectionCapControls } from './SectionCapControls';
 
 export function SectionOverlay() {
   const sectionPlane = useViewerStore((s) => s.sectionPlane);
   const setSectionPlaneAxis = useViewerStore((s) => s.setSectionPlaneAxis);
   const setSectionPlanePosition = useViewerStore((s) => s.setSectionPlanePosition);
   const toggleSectionPlane = useViewerStore((s) => s.toggleSectionPlane);
+  const flipSectionPlane = useViewerStore((s) => s.flipSectionPlane);
   const setActiveTool = useViewerStore((s) => s.setActiveTool);
   const setDrawingPanelVisible = useViewerStore((s) => s.setDrawing2DPanelVisible);
   const drawingPanelVisible = useViewerStore((s) => s.drawing2DPanelVisible);
@@ -83,10 +85,10 @@ export function SectionOverlay() {
 
         {/* Expandable content */}
         {!isPanelCollapsed && (
-          <div className="border-t px-3 pb-3 min-w-64">
+          <div className="border-t px-3 pb-3 min-w-72">
             {/* Direction Selection */}
             <div className="mt-3">
-              <label className="text-xs text-muted-foreground mb-2 block">Direction</label>
+              <div className="text-[10px] uppercase tracking-wider text-muted-foreground mb-1.5">Direction</div>
               <div className="flex gap-1">
                 {(['down', 'front', 'side'] as const).map((axis) => (
                   <Button
@@ -105,16 +107,29 @@ export function SectionOverlay() {
             {/* Position Slider */}
             <div className="mt-3">
               <div className="flex items-center justify-between mb-1">
-                <label className="text-xs text-muted-foreground">Position</label>
-                <input
-                  type="number"
-                  min="0"
-                  max="100"
-                  step="0.1"
-                  value={sectionPlane.position}
-                  onChange={handlePositionChange}
-                  className="w-16 text-xs font-mono bg-muted px-1.5 py-0.5 rounded border-none text-right [appearance:textfield] [&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:appearance-none"
-                />
+                <div className="text-[10px] uppercase tracking-wider text-muted-foreground">Position</div>
+                <div className="flex items-center gap-1">
+                  <Button
+                    variant={sectionPlane.flipped ? 'default' : 'ghost'}
+                    size="icon-sm"
+                    onClick={flipSectionPlane}
+                    aria-pressed={sectionPlane.flipped}
+                    aria-label={sectionPlane.flipped ? 'Unflip cut direction' : 'Flip cut direction'}
+                    title={sectionPlane.flipped ? 'Cut direction is flipped' : 'Flip cut direction'}
+                  >
+                    <FlipHorizontal2 className="h-3 w-3" />
+                  </Button>
+                  <input
+                    type="number"
+                    min="0"
+                    max="100"
+                    step="0.1"
+                    value={sectionPlane.position}
+                    onChange={handlePositionChange}
+                    aria-label="Section plane position percentage"
+                    className="w-16 text-xs font-mono bg-muted px-1.5 py-0.5 rounded border-none text-right [appearance:textfield] [&::-webkit-outer-spin-button]:appearance-none [&::-webkit-inner-spin-button]:appearance-none"
+                  />
+                </div>
               </div>
               <input
                 type="range"
@@ -123,10 +138,14 @@ export function SectionOverlay() {
                 step="0.1"
                 value={sectionPlane.position}
                 onChange={handlePositionChange}
+                aria-label="Section plane position slider"
                 className="w-full h-2 bg-muted rounded-lg appearance-none cursor-pointer accent-primary"
               />
             </div>
 
+            {/* Cap surface controls (hatch, colour, spacing) */}
+            <SectionCapControls />
+
             {/* Show 2D panel button - only when panel is closed */}
             {!drawingPanelVisible && (
               <div className="mt-3 pt-3 border-t">
@@ -156,12 +175,14 @@ export function SectionOverlay() {
       >
         <span className="font-mono text-xs uppercase tracking-wide">
           {sectionPlane.enabled
-            ? `Cutting ${AXIS_INFO[sectionPlane.axis].label.toLowerCase()} at ${sectionPlane.position.toFixed(1)}%`
-            : 'Preview mode'}
+            ? `Cut ${AXIS_INFO[sectionPlane.axis].label.toLowerCase()} at ${sectionPlane.position.toFixed(1)}%${sectionPlane.flipped ? ' (flipped)' : ''}`
+            : 'Clip off — drag slider to cut'}
         </span>
       </div>
 
-      {/* Enable toggle - brutalist style matching Measure tool */}
+      {/* Enable toggle — when OFF the model is not clipped even though the
+          plane visual is shown. Label is explicit so users don't mistake
+          "Preview" for "nothing will happen". */}
       <div className="pointer-events-auto absolute bottom-4 left-1/2 -translate-x-1/2 z-30">
         <button
           onClick={toggleSectionPlane}
@@ -170,9 +191,9 @@ export function SectionOverlay() {
               ? 'bg-primary text-primary-foreground border-primary'
               : 'bg-zinc-100 dark:bg-zinc-900 text-zinc-500 border-zinc-300 dark:border-zinc-700'
           }`}
-          title="Toggle section plane"
+          title={sectionPlane.enabled ? 'Click to disable the cut' : 'Click to enable the cut'}
         >
-          {sectionPlane.enabled ? 'Cutting' : 'Preview'}
+          {sectionPlane.enabled ? 'Clipping' : 'Clip off'}
         </button>
       </div>
 

package/src/components/viewer/useAnimationLoop.ts

@@ -29,6 +29,8 @@ export interface UseAnimationLoopParams {
   lastFrameTimeRef: MutableRefObject<number>;
   mouseIsDraggingRef: MutableRefObject<boolean>;
   activeToolRef: MutableRefObject<string>;
+  /** When set, clips model below this Y value (terrain clipping for Cesium overlay). */
+  terrainClipYRef: MutableRefObject<number | null>;
   hiddenEntitiesRef: MutableRefObject<Set<number>>;
   isolatedEntitiesRef: MutableRefObject<Set<number> | null>;
   selectedEntityIdRef: MutableRefObject<number | null>;
@@ -62,6 +64,7 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
     lastFrameTimeRef,
     mouseIsDraggingRef,
     activeToolRef,
+    terrainClipYRef,
     hiddenEntitiesRef,
     isolatedEntitiesRef,
     selectedEntityIdRef,
@@ -167,10 +170,19 @@ export function useAnimationLoop(params: UseAnimationLoopParams): void {
           isInteracting: isInteractingRef.current || isAnimating,
           buildingRotation: coordinateInfoRef.current?.buildingRotation,
           sectionPlane: activeToolRef.current === 'section' ? {
-            ...sectionPlaneRef.current,
+            axis: sectionPlaneRef.current.axis,
+            position: sectionPlaneRef.current.position,
+            enabled: sectionPlaneRef.current.enabled,
+            flipped: sectionPlaneRef.current.flipped,
+            // Cap rendering settings — the renderer reads these to draw the
+            // filled, hatched cut surfaces.
+            showCap: sectionPlaneRef.current.showCap,
+            showOutlines: sectionPlaneRef.current.showOutlines,
+            capStyle: sectionPlaneRef.current.capStyle,
             min: sectionRangeRef.current?.min,
             max: sectionRangeRef.current?.max,
           } : undefined,
+          terrainClipY: terrainClipYRef.current ?? undefined,
         });
         lastRenderTime = currentTime;
       }

package/src/components/viewer/useGeometryStreaming.ts

@@ -21,6 +21,7 @@
 import { useEffect, useRef, type MutableRefObject } from 'react';
 import type { Renderer } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
+import { logToDesktopTerminal } from '@/services/desktop-logger';
 
 export interface UseGeometryStreamingParams {
   rendererRef: MutableRefObject<Renderer | null>;
@@ -37,6 +38,8 @@ export interface UseGeometryStreamingParams {
   clearPendingMeshColorUpdates: () => void;
   clearPendingColorUpdates: () => void;
   clearColorRef: MutableRefObject<[number, number, number, number]>;
+  releaseGeometryAfterFinalize?: boolean;
+  onGeometryReleased?: () => void;
 }
 
 // Default bounds used when geometry is cleared
@@ -47,6 +50,11 @@ const DEFAULT_BOUNDS = {
 
 const MAX_VALID_COORD = 10000;
 
+function traceGeometrySync(message: string): void {
+  console.log(`[GeomSync] ${message}`);
+  void logToDesktopTerminal('info', `[GeomSync] ${message}`);
+}
+
 export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
   const {
     rendererRef,
@@ -61,6 +69,8 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     clearPendingMeshColorUpdates,
     clearPendingColorUpdates,
     clearColorRef,
+    releaseGeometryAfterFinalize = false,
+    onGeometryReleased,
   } = params;
 
   // ─── Tracking refs ───────────────────────────────────────────────────
@@ -71,6 +81,33 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
   const finalBoundsRefittedRef = useRef(false);
   const cameraSnapshotRef = useRef<{ px: number; py: number; pz: number; tx: number; ty: number; tz: number } | null>(null);
   const prevIsStreamingRef = useRef(isStreaming);
+  const queuePumpTimerRef = useRef<ReturnType<typeof globalThis.setTimeout> | null>(null);
+
+  // Only activate the timer-based queue pump when the tab is background-throttled
+  // (rAF stops firing). In the foreground, the animation loop already drains the
+  // queue every frame — a parallel setTimeout(0) pump doubles the GPU work and
+  // hurts Chrome (Dawn) where each buffer op is an IPC round-trip.
+  const ensureQueuePump = () => {
+    if (queuePumpTimerRef.current !== null) return;
+    if (!globalThis.document?.hidden) return; // rAF is active — let the animation loop drain
+    queuePumpTimerRef.current = globalThis.setTimeout(() => {
+      queuePumpTimerRef.current = null;
+      const renderer = rendererRef.current;
+      if (!renderer || !isInitialized) return;
+      const device = renderer.getGPUDevice();
+      const pipeline = renderer.getPipeline();
+      const scene = renderer.getScene();
+      if (!device || !pipeline || !scene.hasQueuedMeshes()) return;
+      const flushed = scene.flushPending(device, pipeline);
+      if (flushed) {
+        renderer.clearCaches();
+        renderer.requestRender();
+      }
+      if (scene.hasQueuedMeshes()) {
+        ensureQueuePump();
+      }
+    }, 0);
+  };
 
   // ─── Main geometry effect ────────────────────────────────────────────
   // Runs on every geometry change (new file, incremental batch, visibility toggle).
@@ -81,6 +118,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     // Geometry cleared/null — reset so next load is fresh
     if (!geometry) {
       if (lastGeometryLengthRef.current > 0 || lastGeometryRef.current !== null) {
+        traceGeometrySync(`geometry cleared lastLength=${lastGeometryLengthRef.current}`);
         lastGeometryLengthRef.current = 0;
         lastGeometryRef.current = null;
         processedMeshIdsRef.current.clear();
@@ -121,7 +159,9 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     }
 
     if (isNewFile) {
+      traceGeometrySync(`new file currentLength=${currentLength} lastLength=${lastLength} releaseAfterFinalize=${releaseGeometryAfterFinalize}`);
       scene.clear();
+      scene.setEphemeralStreamingMode(releaseGeometryAfterFinalize);
       processedMeshIdsRef.current.clear();
       cameraFittedRef.current = false;
       finalBoundsRefittedRef.current = false;
@@ -132,14 +172,18 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
       geometryBoundsRef.current = { ...DEFAULT_BOUNDS };
     } else if (!isIncremental && currentLength !== lastLength) {
       if (currentLength < lastLength) {
+        traceGeometrySync(`geometry rebuilt after shrink currentLength=${currentLength} lastLength=${lastLength}`);
         // Length decreased (model hidden) — rebuild scene, keep camera
         scene.clear();
+        scene.setEphemeralStreamingMode(releaseGeometryAfterFinalize);
         processedMeshIdsRef.current.clear();
         lastGeometryLengthRef.current = 0;
         lastGeometryRef.current = geometry;
       } else {
+        traceGeometrySync(`geometry rebuilt after replace currentLength=${currentLength} lastLength=${lastLength} releaseAfterFinalize=${releaseGeometryAfterFinalize}`);
         // New file while another was open — full reset
         scene.clear();
+        scene.setEphemeralStreamingMode(releaseGeometryAfterFinalize);
         processedMeshIdsRef.current.clear();
         cameraFittedRef.current = false;
         finalBoundsRefittedRef.current = false;
@@ -193,6 +237,10 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
         if (isStreaming) {
           // Queue for the animation loop — zero GPU work here.
           scene.queueMeshes(newMeshes);
+          // Desktop benchmark windows can become background-throttled, which
+          // stalls requestAnimationFrame-based draining. Keep a timer-based
+          // pump active so large native loads still finish offscreen.
+          ensureQueuePump();
         } else {
           // Non-streaming: process immediately (visibility toggles, etc.)
           scene.appendToBatches(newMeshes, device, pipeline, false);
@@ -230,66 +278,105 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     renderer.requestRender();
   }, [geometry, geometryVersion, coordinateInfo, isInitialized, isStreaming]);
 
+  useEffect(() => {
+    return () => {
+      if (queuePumpTimerRef.current !== null) {
+        globalThis.clearTimeout(queuePumpTimerRef.current);
+        queuePumpTimerRef.current = null;
+      }
+    };
+  }, []);
+
   // ─── Streaming complete: finalize + bounds refit ─────────────────────
   useEffect(() => {
     const renderer = rendererRef.current;
     if (!renderer || !isInitialized) return;
 
     if (prevIsStreamingRef.current && !isStreaming) {
-      // Flush any remaining queued meshes synchronously before finalize
-      const device = renderer.getGPUDevice();
-      const pipeline = renderer.getPipeline();
       const scene = renderer.getScene();
-      if (device && pipeline && scene.hasQueuedMeshes()) {
-        scene.flushPending(device, pipeline);
-      }
-
+      traceGeometrySync(
+        `stream transition complete geometryLength=${geometry?.length ?? 0} queued=${scene.hasQueuedMeshes()} batches=${scene.getBatchedMeshes().length}`
+      );
       renderer.requestRender();
 
-      // Defer heavy work so the browser processes pending input events first.
-      // Streaming fragments keep rendering until proper batches replace them.
       const capturedGeometry = geometry;
-      const timer = setTimeout(() => {
-        const r = rendererRef.current;
-        if (!r) return;
-
-        console.log('[GeomStream] Streaming ended — starting finalize');
-
-        // Compute exact bounds and refit camera (fast ~15ms scan)
-        if (cameraFittedRef.current && !finalBoundsRefittedRef.current && capturedGeometry && capturedGeometry.length > 0) {
-          const t0 = performance.now();
-          const exactBounds = computeBounds(capturedGeometry);
-          console.log(`[GeomStream] computeBounds: ${(performance.now() - t0).toFixed(0)}ms`);
-          if (exactBounds) {
-            if (!userMovedCamera(r, cameraSnapshotRef.current)) {
-              r.getCamera().fitToBounds(exactBounds.min, exactBounds.max);
+      let timeoutId: ReturnType<typeof globalThis.setTimeout> | null = null;
+      let rafId: number | null = null;
+
+      const startFinalize = () => {
+        timeoutId = globalThis.setTimeout(() => {
+          const r = rendererRef.current;
+          if (!r) return;
+
+          console.log('[GeomStream] Streaming ended — starting finalize');
+          traceGeometrySync(
+            `finalize start geometryLength=${capturedGeometry?.length ?? 0} releaseAfterFinalize=${releaseGeometryAfterFinalize}`
+          );
+
+          // Compute exact bounds and refit camera (fast ~15ms scan)
+          if (cameraFittedRef.current && !finalBoundsRefittedRef.current && capturedGeometry && capturedGeometry.length > 0) {
+            const t0 = performance.now();
+            const exactBounds = computeBounds(capturedGeometry);
+            console.log(`[GeomStream] computeBounds: ${(performance.now() - t0).toFixed(0)}ms`);
+            if (exactBounds) {
+              if (!userMovedCamera(r, cameraSnapshotRef.current)) {
+                r.getCamera().fitToBounds(exactBounds.min, exactBounds.max);
+              }
+              geometryBoundsRef.current = exactBounds;
+              finalBoundsRefittedRef.current = true;
             }
-            geometryBoundsRef.current = exactBounds;
-            finalBoundsRefittedRef.current = true;
           }
-        }
 
-        // Time-sliced finalize: rebuild proper batches in ~8ms chunks
-        const dev = r.getGPUDevice();
-        const pipe = r.getPipeline();
-        if (dev && pipe) {
-          const t0 = performance.now();
-          r.getScene().finalizeStreamingAsync(dev, pipe).then(() => {
-            const batchCount = r.getScene().getBatchedMeshes().length;
-            let totalIdx = 0;
-            for (const b of r.getScene().getBatchedMeshes()) totalIdx += b.indexCount;
-            console.log(`[GeomStream] finalizeStreamingAsync complete: ${(performance.now() - t0).toFixed(0)}ms → ${batchCount} consolidated batches, ${(totalIdx / 3 / 1e6).toFixed(1)}M triangles`);
+          // Time-sliced finalize: rebuild proper batches in ~8ms chunks
+          if (releaseGeometryAfterFinalize) {
+            r.getScene().finishEphemeralStreaming();
+            onGeometryReleased?.();
             r.clearCaches();
             r.requestRender();
-          });
+            traceGeometrySync(`ephemeral finalize complete batches=${r.getScene().getBatchedMeshes().length}`);
+            return;
+          }
+
+          const dev = r.getGPUDevice();
+          const pipe = r.getPipeline();
+          if (dev && pipe) {
+            const t0 = performance.now();
+            r.getScene().finalizeStreamingAsync(dev, pipe).then(() => {
+              const batchCount = r.getScene().getBatchedMeshes().length;
+              let totalIdx = 0;
+              for (const b of r.getScene().getBatchedMeshes()) totalIdx += b.indexCount;
+              console.log(`[GeomStream] finalizeStreamingAsync complete: ${(performance.now() - t0).toFixed(0)}ms → ${batchCount} consolidated batches, ${(totalIdx / 3 / 1e6).toFixed(1)}M triangles`);
+              traceGeometrySync(
+                `finalize complete elapsed=${(performance.now() - t0).toFixed(0)}ms batches=${batchCount} queued=${r.getScene().hasQueuedMeshes()}`
+              );
+              r.clearCaches();
+              r.requestRender();
+            });
+          }
+        }, 0);
+      };
+
+      const waitForQueueDrain = () => {
+        const currentRenderer = rendererRef.current;
+        if (!currentRenderer) return;
+        if (!currentRenderer.getScene().hasQueuedMeshes()) {
+          startFinalize();
+          return;
         }
-      }, 0);
+        currentRenderer.requestRender();
+        rafId = requestAnimationFrame(waitForQueueDrain);
+      };
+
+      waitForQueueDrain();
 
       prevIsStreamingRef.current = isStreaming;
-      return () => clearTimeout(timer);
+      return () => {
+        if (timeoutId !== null) globalThis.clearTimeout(timeoutId);
+        if (rafId !== null) cancelAnimationFrame(rafId);
+      };
     }
     prevIsStreamingRef.current = isStreaming;
-  }, [isStreaming, isInitialized]);
+  }, [isStreaming, isInitialized, releaseGeometryAfterFinalize, onGeometryReleased]);
 
   // ─── Mesh color updates (style/material deferred colors) ─────────────
   useEffect(() => {