@ifc-lite/viewer 1.18.0 → 1.19.1

package/src/components/viewer/Viewport.tsx

@@ -8,7 +8,7 @@
 
 import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
 import { Renderer, type VisualEnhancementOptions } from '@ifc-lite/renderer';
-import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
+import type { MeshData, CoordinateInfo, PointCloudAsset } from '@ifc-lite/geometry';
 import { useViewerStore, resolveEntityRef, type MeasurePoint, type SnapVisualization } from '@/store';
 import {
   useSelectionState,
@@ -36,6 +36,8 @@ import { useTouchControls, type TouchState } from './useTouchControls.js';
 import { useKeyboardControls } from './useKeyboardControls.js';
 import { useAnimationLoop } from './useAnimationLoop.js';
 import { useGeometryStreaming } from './useGeometryStreaming.js';
+import { usePointCloudSync } from './usePointCloudSync.js';
+import { usePointCloudLifecycle } from './usePointCloudLifecycle.js';
 import { useRenderUpdates } from './useRenderUpdates.js';
 
 interface ViewportProps {
@@ -43,6 +45,8 @@ interface ViewportProps {
   /** Monotonic counter that increments when geometry changes — used to trigger
    *  streaming effects even when the geometry array reference is stable. */
   geometryVersion?: number;
+  /** Point cloud assets aggregated across visible federated models. */
+  pointClouds?: ReadonlyArray<PointCloudAsset> | null;
   coordinateInfo?: CoordinateInfo;
   computedIsolatedIds?: Set<number> | null;
   modelIdToIndex?: Map<string, number>;
@@ -56,6 +60,7 @@ interface ViewportProps {
 export function Viewport({
   geometry,
   geometryVersion,
+  pointClouds,
   coordinateInfo,
   computedIsolatedIds,
   modelIdToIndex,
@@ -856,6 +861,18 @@ export function Viewport({
     onGeometryReleased,
   });
 
+  usePointCloudSync({
+    rendererRef,
+    isInitialized,
+    pointClouds,
+    hasMeshes: (geometry?.length ?? 0) > 0,
+  });
+
+  usePointCloudLifecycle({
+    rendererRef,
+    isInitialized,
+  });
+
   useRenderUpdates({
     rendererRef,
     isInitialized,

package/src/components/viewer/ViewportContainer.tsx

@@ -20,8 +20,10 @@ import { openIfcFileDialog } from '@/services/file-dialog';
 import { logToDesktopTerminal } from '@/services/desktop-logger';
 import { cacheFileBlobs, formatFileSize, getCachedFile, getRecentFiles, recordRecentFiles, type RecentFileEntry } from '@/lib/recent-files';
 import { isTauri } from '@/lib/platform';
-import { Upload, MousePointer, Layers, Info, Command, AlertTriangle, ChevronDown, ExternalLink, Plus, Clock3 } from 'lucide-react';
-import type { MeshData, CoordinateInfo, GeometryResult } from '@ifc-lite/geometry';
+import { toast } from '@/components/ui/toast';
+import { describeUnsupportedFormat } from '@/hooks/ingest/pointCloudIngest';
+import { Upload, MousePointer, Layers, Info, Command, AlertTriangle, ChevronDown, ExternalLink, Plus, Clock3, Sparkles, ArrowUpRight } from 'lucide-react';
+import type { MeshData, CoordinateInfo, GeometryResult, PointCloudAsset } from '@ifc-lite/geometry';
 import { type IfcDataStore } from '@ifc-lite/parser';
 import { getEffectiveGeoreference } from '@/lib/geo/effective-georef';
 
@@ -174,6 +176,30 @@ export function ViewportContainer() {
     return geometryResult;
   }, [storeModels, geometryResult, modelIdToIndex]);
 
+  /**
+   * Aggregate point clouds across visible models.
+   *
+   * Phase 0: identity-stamping with modelIndex. Returns the same array
+   * reference when nothing has changed so the consumer effect skips work.
+   */
+  const mergedPointClouds = useMemo(() => {
+    const collected: PointCloudAsset[] = [];
+    if (storeModels.size > 0) {
+      for (const [modelId, model] of storeModels) {
+        if (!model.visible) continue;
+        const assets = model.geometryResult?.pointClouds;
+        if (!assets || assets.length === 0) continue;
+        const modelIndex = modelIdToIndex.get(modelId) ?? 0;
+        for (const asset of assets) {
+          collected.push(asset.modelIndex === modelIndex ? asset : { ...asset, modelIndex });
+        }
+      }
+    } else if (geometryResult?.pointClouds) {
+      collected.push(...geometryResult.pointClouds);
+    }
+    return collected;
+  }, [storeModels, geometryResult, modelIdToIndex]);
+
   // Extract georeferencing info merged with any live mutations (for Cesium overlay).
   // Reacts to: model load, Cesium toggle, and every georef field edit.
   const georef = useMemo(() => {
@@ -281,12 +307,22 @@ export function ViewportContainer() {
       return;
     }
 
-    // Filter to supported files (IFC, IFCX, GLB)
-    const supportedFiles = Array.from(e.dataTransfer.files).filter(
+    // Filter to supported files (IFC, IFCX, GLB, point clouds)
+    const allDropped = Array.from(e.dataTransfer.files);
+    const supportedFiles = allDropped.filter(
       f => f.name.endsWith('.ifc') || f.name.endsWith('.ifcx') || f.name.endsWith('.glb')
+        || f.name.toLowerCase().endsWith('.las') || f.name.toLowerCase().endsWith('.laz') || f.name.toLowerCase().endsWith('.ply') || f.name.toLowerCase().endsWith('.pcd') || f.name.toLowerCase().endsWith('.e57')
     );
 
-    if (supportedFiles.length === 0) return;
+    if (supportedFiles.length === 0) {
+      // Tell the user *why* — common case is a Recap project / SketchUp
+      // file dropped because they assumed our viewer would understand it.
+      const explained = allDropped.find((f) => describeUnsupportedFormat(f.name));
+      if (explained) {
+        toast.error(`${explained.name}: ${describeUnsupportedFormat(explained.name)}`);
+      }
+      return;
+    }
 
     recordRecentFiles(supportedFiles.map((file) => ({ name: file.name, size: file.size })));
     void cacheFileBlobs(supportedFiles);
@@ -318,6 +354,7 @@ export function ViewportContainer() {
     // Filter to supported files (IFC, IFCX, GLB)
     const supportedFiles = Array.from(files).filter(
       f => f.name.endsWith('.ifc') || f.name.endsWith('.ifcx') || f.name.endsWith('.glb')
+        || f.name.toLowerCase().endsWith('.las') || f.name.toLowerCase().endsWith('.laz') || f.name.toLowerCase().endsWith('.ply') || f.name.toLowerCase().endsWith('.pcd') || f.name.toLowerCase().endsWith('.e57')
     );
 
     if (supportedFiles.length === 0) return;
@@ -529,7 +566,7 @@ export function ViewportContainer() {
         <input
           ref={fileInputRef}
           type="file"
-          accept=".ifc,.ifcx,.glb"
+          accept=".ifc,.ifcx,.glb,.las,.laz,.ply,.pcd,.e57"
           multiple
           onChange={handleFileSelect}
           className="hidden"
@@ -698,10 +735,18 @@ export function ViewportContainer() {
               IFClite
             </h2>
             <p className="text-zinc-500 dark:text-[#565f89] font-mono text-sm text-center mb-8 border-b border-zinc-200 dark:border-[#3b4261] pb-4 w-full">
-              High-performance web viewer demo
+              IFC toolkit for the open web
             </p>
 
-            {/* Action */}
+            {/*
+              Two-track action area: a primary "open file" track and a
+              secondary "drive with LLM" track sit in mirrored slots — same
+              width, same vertical rhythm, each followed by its own caption
+              line. Reads as one balanced composition instead of a primary
+              CTA + a tacked-on link, while keeping the file-open path
+              visually dominant via the filled-on-hover treatment.
+            */}
+            {/* Track 1 — open / drag */}
             <button
               onClick={async () => {
                 if (!webgpu.supported) {
@@ -737,10 +782,33 @@ export function ViewportContainer() {
               <span>{webgpu.checking ? 'Checking WebGPU...' : webgpu.supported ? 'Open .ifc file' : 'WebGPU Required'}</span>
             </button>
 
-            <p className="mt-3 text-xs font-mono text-zinc-400 dark:text-[#565f89]">
+            <p className="mt-2.5 text-[11px] font-mono text-center text-zinc-400 dark:text-[#565f89]">
               {webgpu.supported ? 'or drag & drop anywhere' : 'file upload disabled'}
             </p>
 
+            {/* Subtle "or" rule — anchors the symmetry between the two tracks */}
+            <div className="mt-5 mb-5 w-full flex items-center gap-3 text-[10px] font-mono uppercase tracking-[0.22em] text-zinc-400 dark:text-[#565f89]">
+              <span className="h-px flex-1 bg-zinc-200 dark:bg-[#3b4261]" />
+              <span>or</span>
+              <span className="h-px flex-1 bg-zinc-200 dark:bg-[#3b4261]" />
+            </div>
+
+            {/* Track 2 — agent / MCP. Compact inline pill, self-centred so
+                it reads as a meta-link sibling to the primary file-open
+                CTA, not a competing full-width button. */}
+            <a
+              href="/mcp"
+              className="group inline-flex self-center items-center gap-1.5 px-3 py-1.5 font-mono text-[11px] border border-dashed border-zinc-300 dark:border-[#3b4261] text-zinc-500 dark:text-[#7a82a5] hover:border-primary hover:text-primary transition-all cursor-pointer"
+            >
+              <Sparkles className="h-3 w-3 transition-transform group-hover:-translate-y-0.5" />
+              <span>Drive with any LLM</span>
+              <ArrowUpRight className="h-2.5 w-2.5 opacity-60 transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+            </a>
+
+            <p className="mt-1.5 text-[10px] font-mono text-center text-zinc-400 dark:text-[#565f89]">
+              via MCP · install or try the playground
+            </p>
+
             {recentFiles.length > 0 && (
               <div className="mt-6 w-full border-t border-zinc-200 dark:border-[#3b4261] pt-4">
                 <div className="mb-3 flex items-center gap-2 text-xs font-mono uppercase tracking-[0.2em] text-zinc-400 dark:text-[#565f89]">
@@ -845,6 +913,7 @@ export function ViewportContainer() {
       <Viewport
         geometry={filteredGeometry}
         geometryVersion={geometryVersion}
+        pointClouds={mergedPointClouds}
         coordinateInfo={mergedGeometryResult?.coordinateInfo}
         computedIsolatedIds={computedIsolatedIds}
         modelIdToIndex={modelIdToIndex}

package/src/components/viewer/ViewportOverlays.tsx

@@ -22,10 +22,11 @@ import { goHomeFromStore } from '@/store/homeView';
 import { useIfc } from '@/hooks/useIfc';
 import { cn } from '@/lib/utils';
 import { isTauri } from '@/lib/platform';
-
-const isDesktop = isTauri();
 import { ViewCube, type ViewCubeRef } from './ViewCube';
 import { AxisHelper, type AxisHelperRef } from './AxisHelper';
+import { PointCloudPanel } from './PointCloudPanel';
+
+const isDesktop = isTauri();
 
 export function ViewportOverlays({ hideViewCube = false }: { hideViewCube?: boolean } = {}) {
   const selectedStoreys = useViewerStore((s) => s.selectedStoreys);
@@ -149,6 +150,7 @@ export function ViewportOverlays({ hideViewCube = false }: { hideViewCube?: bool
 
   return (
     <>
+      <PointCloudPanelMount />
       {/* Bottom-right: Cesium settings overlay OR Navigation controls (Cesium is web-only) */}
       {cesiumEnabled && !isDesktop ? (
         <CesiumSettingsOverlay
@@ -314,3 +316,12 @@ function CesiumSettingsOverlay({
     </div>
   );
 }
+
+/**
+ * Tiny indirection so the panel can subscribe to its own slice without
+ * pulling extra state into the parent overlay component.
+ */
+function PointCloudPanelMount() {
+  const count = useViewerStore((s) => s.pointCloudAssetCount);
+  return <PointCloudPanel assetCount={count} />;
+}

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

@@ -51,14 +51,54 @@ export function AddElementOverlay() {
   // hover points each frame. The tick state is just a number that
   // forces a re-render; the projection itself is read fresh from the
   // store callback.
+  //
+  // Two perf gates:
+  //  1. Skip the loop entirely when there's nothing to project.
+  //     pendingPoints / hoverPoint / autoSpacePreview already trigger
+  //     React re-renders via the store, so the only reason we'd need
+  //     a per-frame tick is to track the camera while content exists.
+  //  2. Only re-render when the camera actually moved since last tick.
+  //     A held tool with a static camera does ~0 work.
+  const getViewpoint = useViewerStore((s) => s.cameraCallbacks.getViewpoint);
+  const hasOverlayContent =
+    pendingPoints.length > 0 ||
+    hoverPoint !== null ||
+    (autoSpacePreview != null && autoSpacePreview.outlines.length > 0);
   const [frameTick, setFrameTick] = useState(0);
   const rafRef = useRef<number | null>(null);
+  const lastViewpointRef = useRef<{
+    px: number; py: number; pz: number;
+    tx: number; ty: number; tz: number;
+    fov: number;
+  } | null>(null);
   useEffect(() => {
     if (activeTool !== 'addElement') return;
+    if (!hasOverlayContent) return;
     let mounted = true;
     const loop = () => {
       if (!mounted) return;
-      setFrameTick((t) => (t + 1) & 0xffff);
+      const vp = getViewpoint?.();
+      if (vp) {
+        const last = lastViewpointRef.current;
+        const moved =
+          !last ||
+          last.px !== vp.position.x || last.py !== vp.position.y || last.pz !== vp.position.z ||
+          last.tx !== vp.target.x  || last.ty !== vp.target.y  || last.tz !== vp.target.z  ||
+          last.fov !== vp.fov;
+        if (moved) {
+          lastViewpointRef.current = {
+            px: vp.position.x, py: vp.position.y, pz: vp.position.z,
+            tx: vp.target.x,   ty: vp.target.y,   tz: vp.target.z,
+            fov: vp.fov,
+          };
+          setFrameTick((t) => (t + 1) & 0xffff);
+        }
+      } else {
+        // Fallback for environments without getViewpoint — preserves the
+        // pre-fix behaviour of an unconditional tick so the projection
+        // can't get stuck stale.
+        setFrameTick((t) => (t + 1) & 0xffff);
+      }
       rafRef.current = requestAnimationFrame(loop);
     };
     rafRef.current = requestAnimationFrame(loop);
@@ -66,8 +106,9 @@ export function AddElementOverlay() {
       mounted = false;
       if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
       rafRef.current = null;
+      lastViewpointRef.current = null;
     };
-  }, [activeTool]);
+  }, [activeTool, hasOverlayContent, getViewpoint]);
 
   const projection = useMemo(
     () => makeProjection(projectToScreen),

package/src/components/viewer/usePointCloudLifecycle.ts

@@ -0,0 +1,64 @@
+/* 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/. */
+
+/**
+ * Tear down streamed point cloud GPU resources when a model is removed.
+ *
+ * Streamed assets (LAS/LAZ) live in a separate ownership bucket on the
+ * renderer (see `PointCloudRenderer`'s `'streamed'` owner tag), so they
+ * survive `setPointClouds` calls. That isolation cuts both ways: nothing
+ * else clears them, so when a model is removed we have to do it here or
+ * the GPU buffers leak for the rest of the session.
+ *
+ * The hook tracks the previous set of `(modelId → handleId)` pairs and,
+ * on every store change, frees the handles for models that disappeared.
+ * Pure cleanup — no state mutation.
+ */
+
+import { useEffect, useRef, type MutableRefObject } from 'react';
+import type { Renderer } from '@ifc-lite/renderer';
+import { useViewerStore } from '@/store';
+
+export interface UsePointCloudLifecycleParams {
+  rendererRef: MutableRefObject<Renderer | null>;
+  isInitialized: boolean;
+}
+
+export function usePointCloudLifecycle(params: UsePointCloudLifecycleParams): void {
+  const { rendererRef, isInitialized } = params;
+  const models = useViewerStore((s) => s.models);
+  const decCount = useViewerStore((s) => s.incrementPointCloudAssetCount);
+  const previousRef = useRef<Map<string, number>>(new Map());
+
+  useEffect(() => {
+    if (!isInitialized) return;
+    const renderer = rendererRef.current;
+    if (!renderer) return;
+
+    const current = new Map<string, number>();
+    for (const [modelId, model] of models) {
+      if (typeof model.pointCloudHandleId === 'number') {
+        current.set(modelId, model.pointCloudHandleId);
+      }
+    }
+
+    // Dispose handles whose model disappeared OR whose model still
+    // exists but was rebound to a new handle (e.g. the user reloaded
+    // the same file and got a fresh streaming session). Without the
+    // rebind branch the old GPU buffers stay allocated for the rest
+    // of the session.
+    for (const [modelId, handleId] of previousRef.current) {
+      const nextHandle = current.get(modelId);
+      if (nextHandle !== handleId) {
+        renderer.removePointCloudAsset({ id: handleId });
+        decCount(-1);
+      }
+    }
+
+    previousRef.current = current;
+    renderer.requestRender();
+  }, [models, isInitialized, rendererRef, decCount]);
+}
+
+export default usePointCloudLifecycle;

package/src/components/viewer/usePointCloudSync.ts

@@ -0,0 +1,98 @@
+/* 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/. */
+
+/**
+ * Sync IFCx-derived point cloud assets to the renderer.
+ *
+ * On every change of the `pointClouds` array we replace the renderer's
+ * asset list and request a fresh frame. When the active scene has no
+ * triangle meshes (the buildingSMART point-cloud-only samples), we
+ * additionally trigger a one-shot camera fit — the geometry streaming
+ * hook bails out early in that case and would otherwise leave points
+ * stranded outside the camera frustum.
+ */
+
+import { useEffect, useRef, type MutableRefObject } from 'react';
+import type { PointColorMode, PointSizeMode, Renderer } from '@ifc-lite/renderer';
+import type { PointCloudAsset } from '@ifc-lite/geometry';
+import { useViewerStore } from '@/store';
+
+export interface UsePointCloudSyncParams {
+  rendererRef: MutableRefObject<Renderer | null>;
+  isInitialized: boolean;
+  pointClouds: ReadonlyArray<PointCloudAsset> | null | undefined;
+  /** True when the scene has triangle meshes — the geometry streaming
+   *  hook owns fit-to-view in that case and we shouldn't fight it. */
+  hasMeshes: boolean;
+}
+
+export function usePointCloudSync(params: UsePointCloudSyncParams): void {
+  const { rendererRef, isInitialized, pointClouds, hasMeshes } = params;
+  const colorMode = useViewerStore((s) => s.pointCloudColorMode) as PointColorMode;
+  const fixedColor = useViewerStore((s) => s.pointCloudFixedColor);
+  const sizeMode = useViewerStore((s) => s.pointCloudSizeMode) as PointSizeMode;
+  const pointSize = useViewerStore((s) => s.pointCloudPointSize);
+  const worldRadius = useViewerStore((s) => s.pointCloudWorldRadius);
+  const roundShape = useViewerStore((s) => s.pointCloudRoundShape);
+  const edlEnabled = useViewerStore((s) => s.pointCloudEdlEnabled);
+  const edlStrength = useViewerStore((s) => s.pointCloudEdlStrength);
+  const setAssetCount = useViewerStore((s) => s.setPointCloudAssetCount);
+  const fittedRef = useRef(false);
+
+  // Reset the one-shot fit flag whenever the asset list identity changes.
+  useEffect(() => {
+    fittedRef.current = false;
+  }, [pointClouds]);
+
+  // Replace IFCx-owned assets when the merged list changes
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+
+    const assets = pointClouds ?? [];
+    renderer.setPointClouds(assets);
+    const count = renderer.getPointCloudAssetCount();
+    setAssetCount(count);
+
+    // Camera fit for points-only scenes — useGeometryStreaming skips its
+    // own fit branch when meshes is empty, so points stay off-screen
+    // unless we step in. Run once per fresh asset list.
+    if (count > 0 && !hasMeshes && !fittedRef.current) {
+      const bounds = renderer.getModelBounds();
+      if (bounds && Number.isFinite(bounds.min.x) && Number.isFinite(bounds.max.x)) {
+        renderer.getCamera().fitToBounds(bounds.min, bounds.max);
+        fittedRef.current = true;
+      }
+    }
+
+    renderer.requestRender();
+  }, [pointClouds, isInitialized, rendererRef, setAssetCount, hasMeshes]);
+
+  // Push color + sizing + shape preferences to the renderer whenever the
+  // user changes them. The slice already clamps numeric ranges so the
+  // shader only ever sees sane values.
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+    renderer.setPointCloudOptions({
+      colorMode,
+      fixedColor,
+      sizeMode,
+      pointSize,
+      worldRadius,
+      roundShape,
+    });
+    renderer.requestRender();
+  }, [colorMode, fixedColor, sizeMode, pointSize, worldRadius, roundShape, isInitialized, rendererRef]);
+
+  // Push EDL toggle + strength to the renderer.
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+    renderer.setEdlOptions({ enabled: edlEnabled, strength: edlStrength });
+    renderer.requestRender();
+  }, [edlEnabled, edlStrength, isInitialized, rendererRef]);
+}
+
+export default usePointCloudSync;

package/src/generated/mcp-catalog.json

@@ -0,0 +1,82 @@
+{
+  "generatedAt": "2026-05-03T09:30:00Z",
+  "version": "0.1.0",
+  "tools": [
+    { "name": "model_info",          "category": "Discovery",  "scope": "read",   "description": "Schema, entity counts, units, georeferencing — the at-a-glance summary of a loaded IFC.", "inputSchema": { "type": "object", "properties": { "model_id": { "type": "string" } } } },
+    { "name": "model_list",          "category": "Discovery",  "scope": "read",   "description": "List every model loaded in the current MCP session.", "inputSchema": { "type": "object" } },
+    { "name": "model_load",          "category": "Discovery",  "scope": "mutate", "description": "Load an additional .ifc from disk into the federated session.", "inputSchema": { "type": "object", "required": ["file_path"], "properties": { "file_path": { "type": "string" }, "model_id": { "type": "string" } } } },
+    { "name": "model_unload",        "category": "Discovery",  "scope": "mutate", "description": "Drop a model from the registry; frees memory.", "inputSchema": { "type": "object", "required": ["model_id"], "properties": { "model_id": { "type": "string" } } } },
+    { "name": "schema_describe",     "category": "Discovery",  "scope": "read",   "description": "Attributes, parent class, and inheritance for any IfcType — useful before mutating.", "inputSchema": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string" }, "include_inherited": { "type": "boolean" } } } },
+
+    { "name": "query_entities",      "category": "Query",      "scope": "read",   "description": "Type + property filters with pagination. Returns expressId, GlobalId, name, type for each match.", "inputSchema": { "type": "object", "properties": { "type": { "type": "string" }, "limit": { "type": "integer" } } } },
+    { "name": "count_entities",      "category": "Query",      "scope": "read",   "description": "Group counts by type, storey, or material — histogram form, not the full set.", "inputSchema": { "type": "object", "properties": { "group_by": { "type": "string", "enum": ["type", "storey", "material"] } } } },
+    { "name": "get_entity",          "category": "Query",      "scope": "read",   "description": "Full attributes + property sets for one entity by GlobalId or expressId.", "inputSchema": { "type": "object", "properties": { "global_id": { "type": "string" }, "express_id": { "type": "integer" } } } },
+    { "name": "get_entities_bulk",   "category": "Query",      "scope": "read",   "description": "Batched get_entity for up to 200 ids at once.", "inputSchema": { "type": "object", "required": ["global_ids"], "properties": { "global_ids": { "type": "array", "items": { "type": "string" } } } } },
+    { "name": "spatial_hierarchy",   "category": "Query",      "scope": "read",   "description": "Project → site → building → storey → space tree, with element counts at each node.", "inputSchema": { "type": "object" } },
+    { "name": "containment_chain",   "category": "Query",      "scope": "read",   "description": "Walk up the spatial chain for one entity (storey + parent + grandparent…).", "inputSchema": { "type": "object", "required": ["global_id"] } },
+    { "name": "relationships",       "category": "Query",      "scope": "read",   "description": "Voids, fills, groups, connections — every IfcRel touching this entity.", "inputSchema": { "type": "object", "required": ["global_id"] } },
+    { "name": "properties_unique",   "category": "Query",      "scope": "read",   "description": "Unique values + counts for one property across a type set (perfect for filter UIs).", "inputSchema": { "type": "object", "required": ["type", "pset", "property"] } },
+    { "name": "materials_list",      "category": "Query",      "scope": "read",   "description": "Distinct materials across the model with usage counts.", "inputSchema": { "type": "object" } },
+    { "name": "classifications_list","category": "Query",      "scope": "read",   "description": "Distinct classification references (system + identification) and how often each is used.", "inputSchema": { "type": "object" } },
+    { "name": "georeferencing",      "category": "Query",      "scope": "read",   "description": "MapConversion, projected CRS, project north, true north — the geo handshake.", "inputSchema": { "type": "object" } },
+    { "name": "units",               "category": "Query",      "scope": "read",   "description": "Length unit scale + the unit assignments declared in the file.", "inputSchema": { "type": "object" } },
+
+    { "name": "geometry_bbox",       "category": "Geometry",   "scope": "read",   "description": "Per-entity axis-aligned bounding box (read from quantity sets when available).", "inputSchema": { "type": "object", "required": ["global_id"] } },
+    { "name": "geometry_volume",     "category": "Geometry",   "scope": "read",   "description": "Net/gross volume in m³ for a single entity or a type aggregate.", "inputSchema": { "type": "object", "required": ["global_id"] } },
+    { "name": "geometry_area",       "category": "Geometry",   "scope": "read",   "description": "Surface area for an entity (front/side/footprint depending on what the IFC carries).", "inputSchema": { "type": "object", "required": ["global_id"] } },
+
+    { "name": "model_audit",         "category": "Validation", "scope": "read",   "description": "Out-of-the-box health score + a list of issues (missing GlobalIds, broken refs, orphan entities).", "inputSchema": { "type": "object" } },
+    { "name": "ids_validate",        "category": "Validation", "scope": "read",   "description": "Run a buildingSMART IDS spec against the loaded model. Per-spec pass/fail with offending entities.", "inputSchema": { "type": "object", "required": ["ids_path"], "properties": { "ids_path": { "type": "string" } } } },
+    { "name": "ids_explain",         "category": "Validation", "scope": "read",   "description": "Parse + summarize an IDS file in plain language — what each spec asks for, in what order.", "inputSchema": { "type": "object", "required": ["ids_path"] } },
+
+    { "name": "entity_set_property", "category": "Mutation",   "scope": "mutate", "description": "Queue a Pset.property write on one entity. Persist later via export_ifc / model_save.", "inputSchema": { "type": "object", "required": ["pset", "name"] } },
+    { "name": "entity_delete_property", "category": "Mutation","scope": "mutate", "description": "Queue a property removal from a Pset. Reversible via mutation_undo.", "inputSchema": { "type": "object", "required": ["pset", "name"] } },
+    { "name": "entity_set_attribute","category": "Mutation",   "scope": "mutate", "description": "Set Name, Description, ObjectType, or Tag on an entity.", "inputSchema": { "type": "object", "required": ["attribute", "value"] } },
+    { "name": "entity_create",       "category": "Mutation",   "scope": "mutate", "description": "Create a new IFC entity with raw STEP attributes and get back its expressId.", "inputSchema": { "type": "object", "required": ["type"] } },
+    { "name": "entity_delete",       "category": "Mutation",   "scope": "mutate", "description": "Delete an entity by expressId/GlobalId. Caller is responsible for cascading rels.", "inputSchema": { "type": "object" } },
+    { "name": "mutation_batch",      "category": "Mutation",   "scope": "mutate", "description": "Apply N mutation ops in order, returning per-step results.", "inputSchema": { "type": "object", "required": ["operations"] } },
+    { "name": "mutation_diff",       "category": "Mutation",   "scope": "read",   "description": "Inspect every queued mutation vs the original parsed state.", "inputSchema": { "type": "object" } },
+    { "name": "mutation_undo",       "category": "Mutation",   "scope": "mutate", "description": "Pop the last N pending mutations off the queue.", "inputSchema": { "type": "object", "properties": { "n": { "type": "integer" } } } },
+    { "name": "model_save",          "category": "Mutation",   "scope": "mutate", "description": "Write the current model (with pending mutations) back to .ifc.", "inputSchema": { "type": "object", "required": ["file_path"] } },
+
+    { "name": "bcf_topic_list",      "category": "BCF",        "scope": "read",   "description": "List BCF topics in this session, optionally filtered by status.", "inputSchema": { "type": "object" } },
+    { "name": "bcf_topic_create",    "category": "BCF",        "scope": "mutate", "description": "Create a topic with title/description/priority and get the GUID for follow-ups.", "inputSchema": { "type": "object", "required": ["title"] } },
+    { "name": "bcf_topic_update",    "category": "BCF",        "scope": "mutate", "description": "Update topic fields or append a comment.", "inputSchema": { "type": "object", "required": ["guid"] } },
+    { "name": "bcf_topic_close",     "category": "BCF",        "scope": "mutate", "description": "Mark a topic resolved (status=Closed).", "inputSchema": { "type": "object", "required": ["guid"] } },
+    { "name": "bcf_viewpoint_create","category": "BCF",        "scope": "mutate", "description": "Attach a selection-based viewpoint (or full viewer state) to a topic.", "inputSchema": { "type": "object", "required": ["guid"] } },
+    { "name": "bcf_export",          "category": "BCF",        "scope": "export", "description": "Export the in-memory BCF project as a .bcfzip file.", "inputSchema": { "type": "object", "required": ["file_path"] } },
+
+    { "name": "bsdd_search",         "category": "bSDD",       "scope": "read",   "description": "Full-text search the buildingSMART Data Dictionary for classes by keyword.", "inputSchema": { "type": "object", "required": ["query"] } },
+    { "name": "bsdd_class",          "category": "bSDD",       "scope": "read",   "description": "Full bSDD class info for an IFC entity name (definition, parent, properties).", "inputSchema": { "type": "object", "required": ["ifc_type"] } },
+    { "name": "bsdd_property_sets",  "category": "bSDD",       "scope": "read",   "description": "Pset_* groups for an IFC type (Pset_WallCommon for IfcWall, etc.).", "inputSchema": { "type": "object", "required": ["ifc_type"] } },
+    { "name": "bsdd_match",          "category": "bSDD",       "scope": "read",   "description": "Suggest matching bSDD classes for an entity in the loaded model.", "inputSchema": { "type": "object" } },
+
+    { "name": "model_diff",          "category": "Diff",       "scope": "read",   "description": "Compare two loaded models. Reports added/removed entities by GlobalId and per-type count deltas.", "inputSchema": { "type": "object", "required": ["a", "b"] } },
+    { "name": "quantity_diff",       "category": "Diff",       "scope": "read",   "description": "Per-entity-type quantity comparison between two models, optionally grouped by storey.", "inputSchema": { "type": "object", "required": ["a", "b"] } },
+
+    { "name": "export_ifc",          "category": "Export",     "scope": "export", "description": "Write the model (with pending mutations) to .ifc/.ifczip on disk.", "inputSchema": { "type": "object", "required": ["file_path"] } },
+    { "name": "export_csv",          "category": "Export",     "scope": "export", "description": "Tabular property/quantity export. Columns may be Pset_X.Property paths.", "inputSchema": { "type": "object" } },
+    { "name": "export_json",         "category": "Export",     "scope": "export", "description": "Structured JSON dump of attributes/properties/quantities for a type set.", "inputSchema": { "type": "object" } },
+    { "name": "export_glb",          "category": "Export",     "scope": "export", "description": "(v0.2) Geometry export to glTF binary — needs the WASM mesh pipeline.", "inputSchema": { "type": "object" } },
+    { "name": "export_ifcx",         "category": "Export",     "scope": "export", "description": "(v0.2) Export to the new IFCx interchange format.", "inputSchema": { "type": "object" } },
+    { "name": "export_pdf_report",   "category": "Export",     "scope": "export", "description": "(v0.5) Branded PDF audit report with charts.", "inputSchema": { "type": "object" } },
+
+    { "name": "viewer_ask",          "category": "Viewer",     "scope": "read",   "description": "Suggest wording the agent can use to ask the user for permission to open the viewer.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_open",         "category": "Viewer",     "scope": "read",   "description": "Boot the in-process WebGL viewer and return its URL for the user to open.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_close",        "category": "Viewer",     "scope": "read",   "description": "Stop the viewer + clear its selection state.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_status",       "category": "Viewer",     "scope": "read",   "description": "Report whether the viewer is open, on what port, and the current selection.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_colorize",     "category": "Viewer",     "scope": "read",   "description": "Paint a set of entities with a color (hex / rgb / named).", "inputSchema": { "type": "object", "required": ["color"] } },
+    { "name": "viewer_isolate",      "category": "Viewer",     "scope": "read",   "description": "Hide everything except the picked set.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_hide",         "category": "Viewer",     "scope": "read",   "description": "Hide the picked set; everything else stays.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_show",         "category": "Viewer",     "scope": "read",   "description": "Show the picked set (un-hide).", "inputSchema": { "type": "object" } },
+    { "name": "viewer_reset",        "category": "Viewer",     "scope": "read",   "description": "Reset visibility + colors to the model defaults.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_fly_to",       "category": "Viewer",     "scope": "read",   "description": "Frame the camera on a set of entities or a bbox.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_set_section",  "category": "Viewer",     "scope": "read",   "description": "Apply an axis-aligned section plane.", "inputSchema": { "type": "object", "required": ["axis", "position"] } },
+    { "name": "viewer_clear_section","category": "Viewer",     "scope": "read",   "description": "Remove the active section plane.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_color_by_storey","category": "Viewer",   "scope": "read",   "description": "Apply a per-storey overlay (built-in viewer preset).", "inputSchema": { "type": "object" } },
+    { "name": "viewer_color_by_property","category": "Viewer", "scope": "read",   "description": "Color a type set by property value, returns a legend the agent can describe.", "inputSchema": { "type": "object", "required": ["type", "pset", "property"] } },
+    { "name": "viewer_get_selection","category": "Viewer",     "scope": "read",   "description": "Return the current selection — type, expressId, GlobalId, name, attributes, materials.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_describe_selection","category": "Viewer","scope": "read",   "description": "Kitchen-sink: every section (attributes, properties, quantities, classifications, materials) for the picked entity.", "inputSchema": { "type": "object" } },
+    { "name": "viewer_wait_for_selection","category": "Viewer","scope": "read",   "description": "Block until the user picks something in the viewer (or timeout).", "inputSchema": { "type": "object" } }
+  ]
+}