@ifc-lite/viewer 1.27.0 → 1.28.1

package/src/hooks/useIfcFederation.ts

@@ -18,8 +18,6 @@ import {
   parseFederatedIfcx,
   type IfcDataStore,
   type FederatedIfcxParseResult,
-  type MapConversion,
-  type ProjectedCRS,
 } from '@ifc-lite/parser';
 import type { CoordinateInfo, MeshData } from '@ifc-lite/geometry';
 import { IfcQuery } from '@ifc-lite/query';
@@ -28,493 +26,10 @@ import { getDynamicBatchConfig } from '../utils/ifcConfig.js';
 import { calculateMeshBounds, createCoordinateInfo } from '../utils/localParsingUtils.js';
 import {
   convertIfcxMeshes,
-  getMaxExpressId,
-  parseGlbViewerModel,
-  parseIfcxViewerModel,
-  parseStepBufferViewerModel,
 } from './ingest/viewerModelIngest.js';
-import {
-  detectPointCloudFormat,
-  ingestPointCloud,
-  type PointCloudFormat,
-} from './ingest/pointCloudIngest.js';
-import { getGlobalRenderer } from './useBCF.js';
-import { readNativeFile, type NativeFileHandle } from '../services/file-dialog.js';
-import { getEffectiveGeoreference, getEffectiveHorizontalScale, hasStandardGeoreferencing, type GeorefMutationDataLike } from '../lib/geo/effective-georef.js';
-import { resolveMapUnitToMetreScale } from '../lib/geo/geo-scale.js';
-import { resolveProjection } from '../lib/geo/reproject.js';
+import { extractModelGeoref, alignGeometryToReference, findReferenceGeorefModel } from './ingest/federationAlign.js';
 import { toast } from '../components/ui/toast.js';
-import proj4 from 'proj4';
 import { acquireFederationLoadSlot, releaseFederationLoadSlot } from './federationLoadGate.js';
-import { acquireFileBuffer } from '../utils/acquireFileBuffer.js';
-
-function isNativeFileHandle(file: File | NativeFileHandle): file is NativeFileHandle {
-  return typeof (file as NativeFileHandle).path === 'string';
-}
-
-function toExactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-  if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
-    return bytes.buffer;
-  }
-  return bytes.slice().buffer;
-}
-
-type FederatedGeometryResult = NonNullable<FederatedModel['geometryResult']>;
-
-interface ModelGeoref {
-  mapConversion: MapConversion;
-  projectedCRS: ProjectedCRS;
-  lengthUnitScale: number;
-  coordinateInfo?: CoordinateInfo;
-}
-
-interface AffineTransform3D {
-  m00: number;
-  m01: number;
-  m02: number;
-  tx: number;
-  m10: number;
-  m11: number;
-  m12: number;
-  ty: number;
-  m20: number;
-  m21: number;
-  m22: number;
-  tz: number;
-}
-
-function getMapUnitScale(georef: ModelGeoref): number {
-  return resolveMapUnitToMetreScale(georef.projectedCRS.mapUnitScale, georef.lengthUnitScale ?? 1);
-}
-
-function getAxis(georef: ModelGeoref): { a: number; o: number; scale: number; denom: number } {
-  const conversion = georef.mapConversion;
-  const a = conversion.xAxisAbscissa ?? 1;
-  const o = conversion.xAxisOrdinate ?? 0;
-  // Use the effective horizontal scale: viewer geometry is already in metres,
-  // so applying IfcMapConversion.Scale raw would double-scale — see issue #595.
-  const mapUnitScale = resolveMapUnitToMetreScale(georef.projectedCRS.mapUnitScale, georef.lengthUnitScale ?? 1);
-  const scale = getEffectiveHorizontalScale(conversion.scale, mapUnitScale, georef.lengthUnitScale ?? 1);
-  const denom = Math.max(a * a + o * o, 1e-12);
-  return { a, o, scale, denom };
-}
-
-function extractModelGeoref(
-  dataStore: IfcDataStore,
-  coordinateInfo?: CoordinateInfo,
-  mutations?: GeorefMutationDataLike,
-): ModelGeoref | null {
-  const georef = getEffectiveGeoreference(dataStore, coordinateInfo, mutations);
-  // Only TRUE georeferencing (real IfcMapConversion + IfcProjectedCRS) may drive
-  // federation alignment. A file with no IfcMapConversion gets a synthesised
-  // `source: 'siteLocation'` georef (EPSG:4326 from IfcSite RefLatitude/Longitude/
-  // Elevation) so it can still be pinned on the location map — but those are
-  // geographic degrees plus a raw, un-unit-scaled site elevation, not a projected
-  // metric frame. buildGeorefAlignmentTransform assumes projected eastings/
-  // northings/height in metres, so feeding it site data places the second model
-  // kilometres away: the BIMcollab ARC/STR pair share a site GUID but carry
-  // RefElevation 0 vs 20000 mm, and the height term lands ARC ~20 km below STR.
-  // Such models have no real georef relationship, so leave them in their own local
-  // frames where they overlay correctly. hasStandardGeoreferencing() excludes
-  // 'siteLocation' (see effective-georef.test.ts). (Regression from #658.)
-  if (!hasStandardGeoreferencing(georef) || !georef?.mapConversion || !georef.projectedCRS?.name) {
-    return null;
-  }
-  return {
-    mapConversion: georef.mapConversion,
-    projectedCRS: georef.projectedCRS,
-    lengthUnitScale: georef.lengthUnitScale,
-    coordinateInfo,
-  };
-}
-
-function crsKey(crs: ProjectedCRS): string {
-  return `${crs.name ?? ''}|${crs.geodeticDatum ?? ''}|${crs.mapProjection ?? ''}|${crs.mapZone ?? ''}`.toUpperCase();
-}
-
-function canAlignInSameProjectedCrs(a: ModelGeoref, b: ModelGeoref): boolean {
-  return crsKey(a.projectedCRS) === crsKey(b.projectedCRS);
-}
-
-function totalYupOffset(coordinateInfo?: CoordinateInfo): { x: number; y: number; z: number } {
-  const shift = coordinateInfo?.originShift ?? { x: 0, y: 0, z: 0 };
-  const rtc = coordinateInfo?.wasmRtcOffset;
-  const rtcYup = rtc ? { x: rtc.x, y: rtc.z, z: -rtc.y } : { x: 0, y: 0, z: 0 };
-  return {
-    x: shift.x + rtcYup.x,
-    y: shift.y + rtcYup.y,
-    z: shift.z + rtcYup.z,
-  };
-}
-
-function emptyBounds() {
-  return {
-    min: { x: Infinity, y: Infinity, z: Infinity },
-    max: { x: -Infinity, y: -Infinity, z: -Infinity },
-  };
-}
-
-function zeroBounds() {
-  return {
-    min: { x: 0, y: 0, z: 0 },
-    max: { x: 0, y: 0, z: 0 },
-  };
-}
-
-function updateBounds(bounds: ReturnType<typeof emptyBounds>, x: number, y: number, z: number): boolean {
-  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return false;
-  bounds.min.x = Math.min(bounds.min.x, x);
-  bounds.min.y = Math.min(bounds.min.y, y);
-  bounds.min.z = Math.min(bounds.min.z, z);
-  bounds.max.x = Math.max(bounds.max.x, x);
-  bounds.max.y = Math.max(bounds.max.y, y);
-  bounds.max.z = Math.max(bounds.max.z, z);
-  return true;
-}
-
-function buildGeorefAlignmentTransform(source: ModelGeoref, reference: ModelGeoref): AffineTransform3D | null {
-  const sourceConv = source.mapConversion;
-  const refConv = reference.mapConversion;
-  const sourceAxis = getAxis(source);
-  const refAxis = getAxis(reference);
-  const refDenom = refAxis.scale * refAxis.denom;
-  if (Math.abs(refDenom) < 1e-12) return null;
-
-  const sourceMapUnitScale = getMapUnitScale(source);
-  const refMapUnitScale = getMapUnitScale(reference);
-  const sourceOffset = totalYupOffset(source.coordinateInfo);
-  const refOffset = totalYupOffset(reference.coordinateInfo);
-
-  const eVx = sourceAxis.scale * sourceAxis.a;
-  const eVz = sourceAxis.scale * sourceAxis.o;
-  const eC = sourceConv.eastings * sourceMapUnitScale
-    + sourceAxis.scale * (sourceAxis.a * sourceOffset.x + sourceAxis.o * sourceOffset.z)
-    - refConv.eastings * refMapUnitScale;
-
-  const nVx = sourceAxis.scale * sourceAxis.o;
-  const nVz = -sourceAxis.scale * sourceAxis.a;
-  const nC = sourceConv.northings * sourceMapUnitScale
-    + sourceAxis.scale * (sourceAxis.o * sourceOffset.x - sourceAxis.a * sourceOffset.z)
-    - refConv.northings * refMapUnitScale;
-
-  const hC = sourceConv.orthogonalHeight * sourceMapUnitScale
-    + sourceOffset.y
-    - refConv.orthogonalHeight * refMapUnitScale;
-
-  const invRefDenom = 1 / refDenom;
-  const xVx = (refAxis.a * eVx + refAxis.o * nVx) * invRefDenom;
-  const xVz = (refAxis.a * eVz + refAxis.o * nVz) * invRefDenom;
-  const xC = (refAxis.a * eC + refAxis.o * nC) * invRefDenom - refOffset.x;
-
-  const yVx = (-refAxis.o * eVx + refAxis.a * nVx) * invRefDenom;
-  const yVz = (-refAxis.o * eVz + refAxis.a * nVz) * invRefDenom;
-  const yC = (-refAxis.o * eC + refAxis.a * nC) * invRefDenom;
-
-  return {
-    m00: xVx,
-    m01: 0,
-    m02: xVz,
-    tx: xC,
-    m10: 0,
-    m11: 1,
-    m12: 0,
-    ty: hC - refOffset.y,
-    m20: -yVx,
-    m21: 0,
-    m22: -yVz,
-    tz: -yC - refOffset.z,
-  };
-}
-
-function isIdentityTransform(transform: AffineTransform3D): boolean {
-  const eps = 1e-7;
-  return Math.abs(transform.m00 - 1) < eps
-    && Math.abs(transform.m01) < eps
-    && Math.abs(transform.m02) < eps
-    && Math.abs(transform.tx) < eps
-    && Math.abs(transform.m10) < eps
-    && Math.abs(transform.m11 - 1) < eps
-    && Math.abs(transform.m12) < eps
-    && Math.abs(transform.ty) < eps
-    && Math.abs(transform.m20) < eps
-    && Math.abs(transform.m21) < eps
-    && Math.abs(transform.m22 - 1) < eps
-    && Math.abs(transform.tz) < eps;
-}
-
-function applyAlignmentTransformAndUpdateBounds(
-  geometry: FederatedGeometryResult,
-  transform: AffineTransform3D,
-  referenceInfo?: CoordinateInfo,
-): void {
-  const bounds = emptyBounds();
-  let found = false;
-
-  for (const mesh of geometry.meshes) {
-    const positions = mesh.positions;
-    for (let i = 0; i < positions.length; i += 3) {
-      const x = positions[i];
-      const y = positions[i + 1];
-      const z = positions[i + 2];
-      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
-        continue;
-      }
-
-      const alignedX = transform.m00 * x + transform.m01 * y + transform.m02 * z + transform.tx;
-      const alignedY = transform.m10 * x + transform.m11 * y + transform.m12 * z + transform.ty;
-      const alignedZ = transform.m20 * x + transform.m21 * y + transform.m22 * z + transform.tz;
-      positions[i] = alignedX;
-      positions[i + 1] = alignedY;
-      positions[i + 2] = alignedZ;
-      found = updateBounds(bounds, alignedX, alignedY, alignedZ) || found;
-    }
-
-    // Rotate normals by the transform's 3×3 linear part (translation omitted)
-    // and renormalize. CRS alignment is a rigid rotation, so the linear part
-    // itself is the correct transform for normals; degenerate results from
-    // zero-length or non-finite inputs are left in place.
-    const normals = mesh.normals;
-    if (normals && normals.length >= 3) {
-      for (let i = 0; i < normals.length; i += 3) {
-        const nx = normals[i];
-        const ny = normals[i + 1];
-        const nz = normals[i + 2];
-        if (!Number.isFinite(nx) || !Number.isFinite(ny) || !Number.isFinite(nz)) {
-          continue;
-        }
-        const rx = transform.m00 * nx + transform.m01 * ny + transform.m02 * nz;
-        const ry = transform.m10 * nx + transform.m11 * ny + transform.m12 * nz;
-        const rz = transform.m20 * nx + transform.m21 * ny + transform.m22 * nz;
-        const len = Math.sqrt(rx * rx + ry * ry + rz * rz);
-        if (!Number.isFinite(len) || len < 1e-12) {
-          continue;
-        }
-        normals[i] = rx / len;
-        normals[i + 1] = ry / len;
-        normals[i + 2] = rz / len;
-      }
-    }
-  }
-
-  geometry.coordinateInfo = {
-    originShift: referenceInfo?.originShift ?? { x: 0, y: 0, z: 0 },
-    originalBounds: found ? bounds : zeroBounds(),
-    shiftedBounds: found ? bounds : zeroBounds(),
-    hasLargeCoordinates: referenceInfo?.hasLargeCoordinates ?? false,
-    wasmRtcOffset: referenceInfo?.wasmRtcOffset,
-    buildingRotation: referenceInfo?.buildingRotation,
-  };
-}
-
-/**
- * Reproject every vertex from a source model's georeference into the reference
- * model's viewer-space frame using proj4 between the two projected CRSs.
- *
- * Used for federated loads where models declare different IfcProjectedCRSs
- * (e.g. EPSG:28992 + EPSG:7415 mixed RD/NAP Dutch sets, or EPSG:25831 UTM +
- * EPSG:28992 mixed). The pipeline per vertex:
- *
- *   viewer(Yup)  ──(source RTC/shift, axis swap)──▶  IFC(Zup, source)
- *   IFC(source)  ──(source MapConversion)──────────▶  source projected (eS,nS,hS)
- *   projected    ──(proj4: srcDef → refDef)────────▶  reference projected (eR,nR)
- *   projected    ──(reference MapConversion inverse)▶  IFC(Zup, reference)
- *   IFC(ref)     ──(axis swap, reference RTC/shift)─▶  viewer(Yup, reference frame)
- *
- * Vertical: height passes through unchanged. Browser-side proj4 has no vertical
- * datum transforms (no NTv2/gtx grids), so cross-CRS vertical mismatches are
- * left for the user to resolve via the per-model orthogonalHeight editor.
- *
- * Normals are NOT rotated. Cross-CRS rotations between projected systems in the
- * same locality are sub-degree, and recomputing per-vertex would require a
- * Jacobian per mesh — acceptable trade-off for now, document if it bites.
- */
-async function alignGeometryAcrossCrs(
-  geometry: FederatedGeometryResult,
-  source: ModelGeoref,
-  reference: ModelGeoref,
-): Promise<boolean> {
-  const sourceProjDef = await resolveProjection(source.projectedCRS);
-  const refProjDef = await resolveProjection(reference.projectedCRS);
-  if (!sourceProjDef || !refProjDef) return false;
-
-  const sourceMapUnitScale = getMapUnitScale(source);
-  const refMapUnitScale = getMapUnitScale(reference);
-  const sourceAxis = getAxis(source);
-  const refAxis = getAxis(reference);
-  const sourceOffset = totalYupOffset(source.coordinateInfo);
-  const refOffset = totalYupOffset(reference.coordinateInfo);
-
-  const refDenom = refAxis.scale * refAxis.denom;
-  if (Math.abs(refDenom) < 1e-12) return false;
-  const invRefDenom = 1 / refDenom;
-
-  const sourceConv = source.mapConversion;
-  const refConv = reference.mapConversion;
-
-  const bounds = emptyBounds();
-  let found = false;
-  let projFailures = 0;
-  let attempts = 0;
-  let firstProjError: unknown = null;
-
-  for (const mesh of geometry.meshes) {
-    const positions = mesh.positions;
-    for (let i = 0; i < positions.length; i += 3) {
-      const vx = positions[i];
-      const vy = positions[i + 1];
-      const vz = positions[i + 2];
-      if (!Number.isFinite(vx) || !Number.isFinite(vy) || !Number.isFinite(vz)) continue;
-
-      // viewer(Y-up, source-local) → world(Y-up) → IFC(Z-up, source)
-      const wx = vx + sourceOffset.x;
-      const wy = vy + sourceOffset.y;
-      const wz = vz + sourceOffset.z;
-      const ifcXs = wx;
-      const ifcYs = -wz;
-      const ifcZs = wy;
-
-      // IFC(source) → source projected (apply source MapConversion)
-      const eS = sourceConv.eastings * sourceMapUnitScale
-        + sourceAxis.scale * (sourceAxis.a * ifcXs - sourceAxis.o * ifcYs);
-      const nS = sourceConv.northings * sourceMapUnitScale
-        + sourceAxis.scale * (sourceAxis.o * ifcXs + sourceAxis.a * ifcYs);
-      const hS = sourceConv.orthogonalHeight * sourceMapUnitScale + ifcZs;
-
-      // source projected → reference projected via proj4
-      attempts += 1;
-      let eR: number;
-      let nR: number;
-      try {
-        const projected = proj4(sourceProjDef, refProjDef, [eS, nS]);
-        eR = projected[0];
-        nR = projected[1];
-      } catch (error) {
-        projFailures += 1;
-        if (firstProjError == null) firstProjError = error;
-        continue;
-      }
-      if (!Number.isFinite(eR) || !Number.isFinite(nR)) {
-        projFailures += 1;
-        continue;
-      }
-      // Height transformed under identity (no vertical datum hop in browser).
-      const hR = hS;
-
-      // reference projected → IFC(reference): invert reference MapConversion
-      const dE = eR - refConv.eastings * refMapUnitScale;
-      const dN = nR - refConv.northings * refMapUnitScale;
-      const ifcXr = invRefDenom * (refAxis.a * dE + refAxis.o * dN);
-      const ifcYr = invRefDenom * (-refAxis.o * dE + refAxis.a * dN);
-      const ifcZr = hR - refConv.orthogonalHeight * refMapUnitScale;
-
-      // IFC(Z-up, reference) → world(Y-up) → viewer(Y-up, reference-local)
-      const refWorldX = ifcXr;
-      const refWorldY = ifcZr;
-      const refWorldZ = -ifcYr;
-      const alignedX = refWorldX - refOffset.x;
-      const alignedY = refWorldY - refOffset.y;
-      const alignedZ = refWorldZ - refOffset.z;
-
-      positions[i] = alignedX;
-      positions[i + 1] = alignedY;
-      positions[i + 2] = alignedZ;
-      found = updateBounds(bounds, alignedX, alignedY, alignedZ) || found;
-    }
-  }
-
-  if (!found) {
-    console.warn(
-      `[ifc-lite] Cross-CRS alignment failed: ${projFailures}/${attempts} `
-      + `vertex transforms failed for ${source.projectedCRS.name} → ${reference.projectedCRS.name}; `
-      + 'no vertices were successfully reprojected. Leaving geometry untouched.',
-      firstProjError,
-    );
-    return false;
-  }
-
-  geometry.coordinateInfo = {
-    originShift: reference.coordinateInfo?.originShift ?? { x: 0, y: 0, z: 0 },
-    originalBounds: bounds,
-    shiftedBounds: bounds,
-    hasLargeCoordinates: reference.coordinateInfo?.hasLargeCoordinates ?? false,
-    wasmRtcOffset: reference.coordinateInfo?.wasmRtcOffset,
-    buildingRotation: reference.coordinateInfo?.buildingRotation,
-  };
-
-  if (projFailures > 0) {
-    console.warn(
-      `[ifc-lite] Cross-CRS alignment: ${projFailures}/${attempts} vertex transforms `
-      + `failed from ${source.projectedCRS.name} to ${reference.projectedCRS.name}. `
-      + 'Those vertices are left at their original positions.',
-      firstProjError,
-    );
-  }
-  return true;
-}
-
-export type FederationAlignmentStatus = 'same-crs' | 'reprojected' | 'identity' | 'failed';
-
-/**
- * Route alignment to the right strategy based on whether the source and
- * reference share a projected CRS. Returns a status describing how the model
- * was placed in the federation, suitable for surfacing in the UI.
- */
-async function alignGeometryToReference(
-  geometry: FederatedGeometryResult,
-  source: ModelGeoref,
-  reference: ModelGeoref,
-): Promise<FederationAlignmentStatus> {
-  if (canAlignInSameProjectedCrs(source, reference)) {
-    const transform = buildGeorefAlignmentTransform(source, reference);
-    if (!transform) return 'failed';
-    if (isIdentityTransform(transform)) return 'identity';
-    applyAlignmentTransformAndUpdateBounds(geometry, transform, reference.coordinateInfo);
-    return 'same-crs';
-  }
-  const ok = await alignGeometryAcrossCrs(geometry, source, reference);
-  return ok ? 'reprojected' : 'failed';
-}
-
-/**
- * Select the federation anchor model.
- *
- * Resolution order:
- *   1. `anchorModelIdOverride` from the store, if it points to a loaded model
- *      with a valid georeference.
- *   2. Earliest `loadedAt` model with a valid georeference (the default — gives
- *      a stable anchor across loads while letting the user override when they
- *      want a different model to drive the world frame).
- */
-function findReferenceGeorefModel(): { modelId: string; georef: ModelGeoref } | null {
-  const state = useViewerStore.getState();
-  const override = state.anchorModelIdOverride;
-  if (override) {
-    const model = state.models.get(override) as FederatedModel | undefined;
-    if (model?.ifcDataStore && model.geometryResult) {
-      const georef = extractModelGeoref(
-        model.ifcDataStore,
-        model.geometryResult.coordinateInfo,
-        state.georefMutations.get(override),
-      );
-      if (georef) return { modelId: override, georef };
-    }
-    // Fall through if the override no longer resolves — keeps loads
-    // recoverable even if the user removed the anchor they had pinned.
-  }
-
-  const modelEntries = Array.from(state.models.entries()) as Array<[string, FederatedModel]>;
-  const sorted = [...modelEntries].sort(([, a], [, b]) => (a.loadedAt ?? 0) - (b.loadedAt ?? 0));
-  for (const [modelId, model] of sorted) {
-    if (!model.ifcDataStore || !model.geometryResult) continue;
-    const georef = extractModelGeoref(
-      model.ifcDataStore,
-      model.geometryResult.coordinateInfo,
-      state.georefMutations.get(modelId),
-    );
-    if (georef) return { modelId, georef };
-  }
-  return null;
-}
 
 /**
  * Extended data store type for IFCX (IFC5) files.
@@ -537,7 +52,11 @@ export interface IfcxDataStore extends IfcDataStore {
  * Includes addModel, removeModel, federated IFCX loading, overlay management,
  * and ID resolution helpers
  */
-export function useIfcFederation() {
+export function useIfcFederation(
+  // The ONE canonical loader. Federated adds route through it (target
+  // 'federated') so model #1 and model #N share an identical pipeline.
+  loadFile: (file: File, target?: import('./useIfcLoader.js').LoadTarget) => Promise<void>,
+) {
   const {
     setLoading,
     setError,
@@ -583,7 +102,7 @@ export function useIfcFederation() {
    * Returns the model ID on success, null on failure
    */
   const addModel = useCallback(async (
-    file: File | NativeFileHandle,
+    file: File,
     options?: {
       name?: string;
       modelId?: string;
@@ -605,336 +124,48 @@ export function useIfcFederation() {
     const fileSizeForGateMB = (typeof (file as File).size === 'number' ? (file as File).size : 0) / (1024 * 1024);
     const gateSlot = await acquireFederationLoadSlot(fileSizeForGateMB);
     try {
-      // IMPORTANT: Before adding a new model, check if there's a legacy model
-      // (loaded via loadFile) that's not in the Map yet. If so, migrate it first.
-      const currentModels = useViewerStore.getState().models;
-      const currentIfcDataStore = useViewerStore.getState().ifcDataStore;
-      const currentGeometryResult = useViewerStore.getState().geometryResult;
-
-      if (currentModels.size === 0 && currentIfcDataStore && currentGeometryResult) {
-        // Migrate the legacy model to the Map
-        // Legacy model has offset 0 (IDs are unchanged)
-        const legacyModelId = crypto.randomUUID();
-        const legacyName = currentIfcDataStore.spatialHierarchy?.project?.name || 'Model 1';
-
-        // Find max expressId in legacy model for registry
-        // IMPORTANT: Include ALL entities, not just meshes, for proper globalId resolution
-        const legacyMeshes = currentGeometryResult.meshes || [];
-        const legacyMaxExpressIdFromMeshes = legacyMeshes.reduce((max: number, m: MeshData) => Math.max(max, m.expressId), 0);
-        // FIXED: Use iteration instead of spread to avoid stack overflow with large Maps
-        let legacyMaxExpressIdFromEntities = 0;
-        if (currentIfcDataStore.entityIndex?.byId) {
-          for (const key of currentIfcDataStore.entityIndex.byId.keys()) {
-            if (key > legacyMaxExpressIdFromEntities) legacyMaxExpressIdFromEntities = key;
-          }
-        }
-        const legacyMaxExpressId = Math.max(legacyMaxExpressIdFromMeshes, legacyMaxExpressIdFromEntities);
-
-        // Register legacy model with offset 0 (IDs already in use as-is)
-        const legacyOffset = registerModelOffset(legacyModelId, legacyMaxExpressId);
-
-        const legacyModel: FederatedModel = {
-          id: legacyModelId,
-          name: legacyName,
-          ifcDataStore: currentIfcDataStore,
-          geometryResult: currentGeometryResult,
-          visible: true,
-          collapsed: false,
-          schemaVersion: 'IFC4',
-          loadedAt: Date.now() - 1000,
-          fileSize: 0,
-          sourceFile: undefined,
-          idOffset: legacyOffset,
-          maxExpressId: legacyMaxExpressId,
-        };
-        storeAddModel(legacyModel);
-      }
-
+      // (Removed the legacy→Map migration: every model — including model #1 —
+      // now registers in the FederationRegistry + models Map via loadFile's
+      // upsertModel/finalizeModel, so a top-level-only "legacy" model can no
+      // longer exist. See PR description for the audit.)
       setLoading(true);
       setError(null);
       setProgress({ phase: 'Loading file', percent: 0 });
 
-      // Read file from disk. The browser path streams files above
-      // `STREAM_SAB_THRESHOLD` directly into a SharedArrayBuffer, eliminating
-      // the doubled peak (ArrayBuffer + SAB) of `await file.arrayBuffer()`
-      // when the geometry pipeline copies into its own SAB. The native path
-      // still reads via Tauri's Rust IPC because it bounds memory differently.
-      // (#600)
-      let buffer: ArrayBuffer;
-      if (isNativeFileHandle(file)) {
-        buffer = toExactArrayBuffer(await readNativeFile(file.path));
-      } else {
-        // The cast preserves the previous ArrayBuffer-shaped contract for
-        // every downstream consumer. When the underlying store is a SAB,
-        // downstream code only ever reads bytes via `new Uint8Array(buffer)`
-        // / `new DataView(buffer)`, both of which work on either backing
-        // store. The cast is purely type-system; runtime is identical.
-        const acquired = await acquireFileBuffer(file as File);
-        buffer = acquired.buffer as ArrayBuffer;
-      }
-      const fileSizeMB = buffer.byteLength / (1024 * 1024);
-
-      // Detect point cloud formats first — we never run them through
-      // detectFormat() (which is IFC-shaped) because they have their own
-      // streaming pipeline that bypasses geometryResult.meshes.
-      const pointCloudFormat = detectPointCloudFormat(file.name, buffer);
-
-      // Detect file format
-      const format: ReturnType<typeof detectFormat> | PointCloudFormat =
-        pointCloudFormat ?? detectFormat(buffer);
-
-      let parsedDataStore: IfcDataStore | null = null;
-      let parsedGeometry: FederatedModel['geometryResult'] = null;
-      let schemaVersion: SchemaVersion = 'IFC4';
-      // Renderer handle for streamed point clouds; surviving model lifecycle
-      // depends on persisting it onto the FederatedModel record.
-      let pointCloudHandleId: number | undefined;
-
-      if (format === 'las' || format === 'laz' || format === 'ply' || format === 'pcd' || format === 'e57' || format === 'pts' || format === 'xyz') {
-        const renderer = getGlobalRenderer();
-        if (!renderer) {
-          setError('Renderer not initialised — try again after the viewer mounts.');
-          setLoading(false);
-          return null;
-        }
-        setProgress({ phase: `Streaming ${format.toUpperCase()}`, percent: 5 });
-        const blob = isNativeFileHandle(file)
-          ? new Blob([buffer])
-          : (file as File);
-        const incCount = useViewerStore.getState().incrementPointCloudAssetCount;
-        const ingest = ingestPointCloud({
-          format,
-          blob,
-          fileName: file.name,
-          buffer,
-          renderer,
-          onProgress: setProgress,
-          onAssetCountDelta: incCount,
-        });
-        // Expose cancellation while the stream is in-flight. Capture
-        // the canceller as a named ref so the cleanup can verify the
-        // store still points at us before clearing — a second
-        // addModel() that began before this one settles must not lose
-        // its Cancel button to our finally block.
-        const { setActiveStreamCanceller } = useViewerStore.getState();
-        const cancelStream = () => ingest.streamHandle.cancel();
-        setActiveStreamCanceller(cancelStream);
-        // ingest.done rejects on stream errors; ingestPointCloud's onError
-        // callback already calls removePointCloudAsset + incCount(-1), so
-        // the outer catch must NOT repeat that cleanup or the count goes
-        // negative when other point clouds are still loaded.
-        try {
-          await ingest.done;
-        } finally {
-          if (useViewerStore.getState().activeStreamCanceller === cancelStream) {
-            setActiveStreamCanceller(null);
-          }
-        }
-        parsedDataStore = ingest.dataStore;
-        parsedGeometry = ingest.geometryResult;
-        schemaVersion = ingest.schemaVersion;
-        pointCloudHandleId = ingest.rendererHandle.id;
-      } else if (format === 'ifcx') {
-        setProgress({ phase: 'Parsing IFCX (client-side)', percent: 10 });
-        try {
-          const result = await parseIfcxViewerModel(buffer, setProgress);
-          parsedDataStore = result.dataStore;
-          parsedGeometry = result.geometryResult;
-          schemaVersion = result.schemaVersion;
-        } catch (error) {
-          if (error instanceof Error && error.message === 'overlay-only-ifcx') {
-            console.warn(`[useIfc] IFCX file "${file.name}" has no geometry - this is an overlay file.`);
-            setError(`"${file.name}" is an overlay file with no geometry. Please load it together with a base IFCX file (select all files at once for federated loading).`);
-            setLoading(false);
-            return null;
-          }
-          throw error;
-        }
-      } else if (format === 'glb') {
-        setProgress({ phase: 'Parsing GLB', percent: 10 });
-        const result = await parseGlbViewerModel(buffer);
-        parsedDataStore = result.dataStore;
-        parsedGeometry = result.geometryResult;
-        schemaVersion = result.schemaVersion;
-      } else {
-        setProgress({ phase: 'Starting geometry streaming', percent: 10 });
-
-        // For federated models: use the first model's RTC offset so all models
-        // share the same coordinate origin. This ensures pixel-perfect alignment
-        // without error-prone delta adjustments.
-        let sharedRtcOffset: { x: number; y: number; z: number } | undefined;
-        const existingModelsForRtc = Array.from(useViewerStore.getState().models.values()) as FederatedModel[];
-        if (existingModelsForRtc.length > 0) {
-          const sorted = [...existingModelsForRtc].sort((a, b) => (a.loadedAt ?? 0) - (b.loadedAt ?? 0));
-          sharedRtcOffset = sorted.find(
-            (model) => model.geometryResult?.coordinateInfo?.wasmRtcOffset != null,
-          )?.geometryResult?.coordinateInfo?.wasmRtcOffset;
-        }
-
-        const result = await parseStepBufferViewerModel({
-          fileName: file.name,
-          buffer,
-          fileSizeMB,
-          getDynamicBatchSize: getDynamicBatchConfig,
-          onProgress: setProgress,
-          sharedRtcOffset,
-        });
-        parsedDataStore = result.dataStore;
-        parsedGeometry = result.geometryResult;
-        schemaVersion = result.schemaVersion;
-      }
-
-      if (!parsedDataStore || !parsedGeometry) {
-        throw new Error('Failed to parse file');
+      // Pick the shared RTC origin from the earliest existing model so every
+      // federated model lands in one coordinate space (pixel-perfect alignment,
+      // no post-shift). Threaded into the canonical loader below.
+      let sharedRtcOffset: { x: number; y: number; z: number } | undefined;
+      const existingModelsForRtc = Array.from(useViewerStore.getState().models.values()) as FederatedModel[];
+      if (existingModelsForRtc.length > 0) {
+        const sorted = [...existingModelsForRtc].sort((a, b) => (a.loadedAt ?? 0) - (b.loadedAt ?? 0));
+        sharedRtcOffset = sorted.find(
+          (model) => model.geometryResult?.coordinateInfo?.wasmRtcOffset != null,
+        )?.geometryResult?.coordinateInfo?.wasmRtcOffset;
       }
 
-      const referenceSelection = findReferenceGeorefModel();
-      const referenceGeoref = referenceSelection?.georef ?? null;
-      // Include any georef edits the user has already saved for this model so
-      // that a reload after editing reflects the new placement. Without this,
-      // extractModelGeoref reads only the raw parsed metadata and mutations
-      // are silently ignored.
-      const parsedGeorefMutations = useViewerStore.getState().georefMutations.get(modelId);
-      const parsedGeoref = extractModelGeoref(
-        parsedDataStore,
-        parsedGeometry.coordinateInfo,
-        parsedGeorefMutations,
-      );
-      // Cache of pre-alignment vertex positions/normals for realignFederation().
-      // Only populated when alignment actually runs, so single-model loads pay
-      // no memory cost. See FederatedModel.preAlignmentPositions for rationale.
-      let preAlignmentPositions: Float32Array[] | undefined;
-      let preAlignmentNormals: (Float32Array | undefined)[] | undefined;
-      let preAlignmentCoordinateInfo: CoordinateInfo | undefined;
-      let federationAlignmentStatus: FederatedModel['federationAlignmentStatus'] = 'none';
-
-      if (referenceGeoref && parsedGeoref) {
-        // referenceSelection.modelId !== modelId always holds — the anchor was
-        // already in the store before this addModel call.
-        setProgress({ phase: 'Aligning georeferenced model', percent: 90 });
-        preAlignmentPositions = parsedGeometry.meshes.map((mesh) => new Float32Array(mesh.positions));
-        preAlignmentNormals = parsedGeometry.meshes.map((mesh) =>
-          mesh.normals && mesh.normals.length > 0 ? new Float32Array(mesh.normals) : undefined,
-        );
-        preAlignmentCoordinateInfo = parsedGeometry.coordinateInfo;
-        const status = await alignGeometryToReference(parsedGeometry, parsedGeoref, referenceGeoref);
-        federationAlignmentStatus = status;
-        if (status === 'reprojected') {
-          toast.info(
-            `Reprojected "${file.name}" from ${parsedGeoref.projectedCRS.name} `
-            + `to ${referenceGeoref.projectedCRS.name} for federation alignment.`,
-          );
-        } else if (status === 'failed') {
-          toast.error(
-            `Could not align "${file.name}" with the federation anchor — `
-            + `${parsedGeoref.projectedCRS.name} → ${referenceGeoref.projectedCRS.name} `
-            + 'reprojection failed. The model is shown in its own local frame and may '
-            + 'appear at the wrong real-world position.',
-          );
-        }
-      } else if (parsedGeoref) {
-        // This load is itself the federation anchor (first georeferenced model
-        // in the federation, or the only one). Surface that to the UI.
-        federationAlignmentStatus = 'anchor';
-      }
-
-      // =========================================================================
-      // FEDERATION REGISTRY: Transform expressIds to globally unique IDs
-      // This is the BULLETPROOF fix for multi-model ID collisions
-      // =========================================================================
-
-      // Step 1: Find max expressId in this model
-      // IMPORTANT: Use ALL entities from data store, not just meshes
-      // Spatial containers (IfcProject, IfcSite, etc.) don't have geometry but need valid globalId resolution
-      const maxExpressId = getMaxExpressId(parsedDataStore, parsedGeometry.meshes);
-
-      // Step 2: Register with federation registry to get unique offset
-      const idOffset = registerModelOffset(modelId, maxExpressId);
+      // THE canonical load path. loadFile acquires bytes, detects format
+      // (IFC / IFCX / GLB / point cloud), produces geometry through the single
+      // GeometryProcessor pipeline, parses the data store, and — because the
+      // target is federated — finalizeModel aligns to the anchor, offsets ids,
+      // builds the spatial index, and registers the model via addModel. loadFile
+      // awaits that finalize, so on return the model is already in the map.
+      await loadFile(file, {
+        kind: 'federated',
+        modelId,
+        name: options?.name,
+        visible: options?.visible,
+        collapsed: options?.collapsed,
+        loadedAt: options?.loadedAt,
+        sharedRtcOffset,
+      });
 
-      // Step 3: Transform ALL mesh expressIds to globalIds
-      // globalId = originalExpressId + offset
-      // This ensures no two models can have the same ID
-      if (idOffset > 0) {
-        for (const mesh of parsedGeometry.meshes) {
-          mesh.expressId = mesh.expressId + idOffset;
-        }
-        // Point clouds need the same offset so picking / isolation /
-        // property lookup resolve through the FederationRegistry's
-        // global ID space — otherwise two pointcloud models with the
-        // same local expressId collide.
-        for (const asset of parsedGeometry.pointClouds ?? []) {
-          asset.expressId = asset.expressId + idOffset;
-        }
+      if (loadSessionRef.current !== currentSession) return null;
+      const registered = useViewerStore.getState().models.has(modelId);
+      if (registered) {
+        console.log(`[ifc-lite] Added model ${file.name} (${fileSizeForGateMB.toFixed(1)}MB) in ${(performance.now() - addStart).toFixed(0)}ms`);
       }
-      // Streamed point cloud: the GPU asset was opened with a synthetic
-      // local expressId. After registerModelOffset() hands us an
-      // idOffset, the renderer needs to emit the post-offset globalId
-      // in picking + selection outputs — otherwise picks resolve to
-      // the local id and collide across federated models. The shader
-      // reads expressId from a per-asset uniform (`flags.x`) so this
-      // is just a metadata update; no GPU buffer rewrite.
-      if (idOffset > 0 && pointCloudHandleId !== undefined) {
-        const renderer = getGlobalRenderer();
-        if (renderer && parsedGeometry.pointClouds && parsedGeometry.pointClouds.length > 0) {
-          // Use the asset that's already had idOffset folded in above
-          // as the source of truth for the global id.
-          const asset = parsedGeometry.pointClouds[0];
-          renderer.relabelPointCloudAsset({ id: pointCloudHandleId }, asset.expressId);
-        }
-      }
-
-      // =========================================================================
-      // COORDINATE ALIGNMENT: All federated models use the same shared RTC offset
-      // (passed to WASM during parsing above), so no post-processing vertex
-      // adjustment is needed. All models are already in the same coordinate space.
-      // =========================================================================
-
-      // Build spatial index AFTER ID offset + RTC alignment so it stores
-      // correct globalIds and final world-space positions.
-      buildSpatialIndexGuarded(parsedGeometry.meshes, parsedDataStore, setIfcDataStore);
-
-      // Create the federated model with offset info
-      const federatedModel: FederatedModel = {
-        id: modelId,
-        name: options?.name ?? file.name,
-        ifcDataStore: parsedDataStore,
-        geometryResult: parsedGeometry,
-        visible: options?.visible ?? true,
-        collapsed: options?.collapsed ?? hasModels(), // Collapse if not first model
-        schemaVersion,
-        loadedAt: options?.loadedAt ?? Date.now(),
-        fileSize: buffer.byteLength,
-        sourceFile: file,
-        idOffset,
-        maxExpressId,
-        pointCloudHandleId,
-        preAlignmentPositions,
-        preAlignmentNormals,
-        preAlignmentCoordinateInfo,
-        federationAlignmentStatus,
-      };
-
-      // Add to store
-      storeAddModel(federatedModel);
-
-      // Don't touch the legacy top-level setters for added models. When this
-      // is the first model, modelSlice.addModel already mirrored it into the
-      // top-level fields. When subsequent models are added, activeModelId
-      // stays on the first model — writing here would alias the new model's
-      // data into the active (first) model's per-model entry and cause both
-      // viewport slots to render the same mesh (issue #661, PR #792).
-      //
-      // An earlier draft of this branch called `setActiveModel(modelId)`
-      // here, which also fixed #661 but had the side-effect of stealing
-      // focus to every added model — confusing UX. The main-branch fix
-      // (drop the legacy calls; keep activeModelId on the first model)
-      // is preferred and was kept on merge.
-
-      setProgress({ phase: 'Complete', percent: 100 });
-      setLoading(false);
-      console.log(`[ifc-lite] Added model ${file.name} (${fileSizeMB.toFixed(1)}MB) in ${(performance.now() - addStart).toFixed(0)}ms`);
-
-      return modelId;
+      return registered ? modelId : null;
 
     } catch (err) {
       // Only mutate shared loading/error/progress state if our session
@@ -963,7 +194,7 @@ export function useIfcFederation() {
     } finally {
       releaseFederationLoadSlot(gateSlot);
     }
-  }, [setLoading, setError, setProgress, setIfcDataStore, setGeometryResult, storeAddModel, hasModels, registerModelOffset]);
+  }, [loadFile, setLoading, setError, setProgress]);
 
   /**
    * Re-apply federation alignment using the currently selected anchor