@ifc-lite/viewer 1.19.0 → 1.21.0

package/src/components/viewer/useTouchControls.ts

@@ -11,7 +11,9 @@ import { useEffect, type MutableRefObject, type RefObject } from 'react';
 import type { Renderer, PickResult } from '@ifc-lite/renderer';
 import type { MeshData } from '@ifc-lite/geometry';
 import type { SectionPlane } from '@/store';
-import { getEntityCenter } from '../../utils/viewportUtils.js';
+
+/** Locked gesture mode for 2-finger interactions */
+type TwoFingerGesture = 'none' | 'pinch' | 'pan';
 
 export interface TouchState {
   touches: Touch[];
@@ -21,6 +23,12 @@ export interface TouchState {
   tapStartPos: { x: number; y: number };
   didMove: boolean;
   multiTouch: boolean;
+  /** Locked 2-finger gesture mode (reset on finger lift) */
+  twoFingerGesture: TwoFingerGesture;
+  /** Accumulated distance change since 2-finger gesture start */
+  gestureDistanceAccum: number;
+  /** Accumulated center movement since 2-finger gesture start */
+  gesturePanAccum: number;
 }
 
 export interface UseTouchControlsParams {
@@ -70,6 +78,40 @@ export function useTouchControls(params: UseTouchControlsParams): void {
     const camera = renderer.getCamera();
     const touchState = touchStateRef.current;
 
+    // Anchor the orbit pivot to the 3D point directly under a finger.
+    // Touch UX: prefer the finger's actual hit, then fall back to ray-projection
+    // at current view distance — never to a selected entity's center, which
+    // would pivot far from the user's touch and feel disconnected.
+    const anchorOrbitPivotUnderFinger = (touch: Touch) => {
+      const rect = canvas.getBoundingClientRect();
+      const tx = touch.clientX - rect.left;
+      const ty = touch.clientY - rect.top;
+      const hit = renderer.raycastScene(tx, ty, {
+        hiddenIds: hiddenEntitiesRef.current,
+        isolatedIds: isolatedEntitiesRef.current,
+      });
+      if (hit?.intersection) {
+        camera.setOrbitCenter(hit.intersection.point);
+        return;
+      }
+      const ray = camera.unprojectToRay(tx, ty, canvas.width, canvas.height);
+      const target = camera.getTarget();
+      const toTarget = {
+        x: target.x - ray.origin.x,
+        y: target.y - ray.origin.y,
+        z: target.z - ray.origin.z,
+      };
+      const d = Math.max(
+        1,
+        toTarget.x * ray.direction.x + toTarget.y * ray.direction.y + toTarget.z * ray.direction.z,
+      );
+      camera.setOrbitCenter({
+        x: ray.origin.x + ray.direction.x * d,
+        y: ray.origin.y + ray.direction.y * d,
+        z: ray.origin.z + ray.direction.z * d,
+      });
+    };
+
     const handleTouchStart = async (e: TouchEvent) => {
       e.preventDefault();
       touchState.touches = Array.from(e.touches);
@@ -92,39 +134,7 @@ export function useTouchControls(params: UseTouchControlsParams): void {
         };
         touchState.didMove = false;
 
-        // Set orbit pivot to the 3D point under the finger.
-        // On miss, place pivot at current distance along the finger ray.
-        const rect = canvas.getBoundingClientRect();
-        const tx = touchState.touches[0].clientX - rect.left;
-        const ty = touchState.touches[0].clientY - rect.top;
-        const hit = renderer.raycastScene(tx, ty, {
-          hiddenIds: hiddenEntitiesRef.current,
-          isolatedIds: isolatedEntitiesRef.current,
-        });
-        if (hit?.intersection) {
-          camera.setOrbitCenter(hit.intersection.point);
-        } else if (selectedEntityIdRef.current) {
-          const center = getEntityCenter(geometryRef.current, selectedEntityIdRef.current);
-          if (center) {
-            camera.setOrbitCenter(center);
-          } else {
-            camera.setOrbitCenter(null);
-          }
-        } else {
-          const ray = camera.unprojectToRay(tx, ty, canvas.width, canvas.height);
-          const target = camera.getTarget();
-          const toTarget = {
-            x: target.x - ray.origin.x,
-            y: target.y - ray.origin.y,
-            z: target.z - ray.origin.z,
-          };
-          const d = Math.max(1, toTarget.x * ray.direction.x + toTarget.y * ray.direction.y + toTarget.z * ray.direction.z);
-          camera.setOrbitCenter({
-            x: ray.origin.x + ray.direction.x * d,
-            y: ray.origin.y + ray.direction.y * d,
-            z: ray.origin.z + ray.direction.z * d,
-          });
-        }
+        anchorOrbitPivotUnderFinger(touchState.touches[0]);
       } else if (touchState.touches.length === 1) {
         // Single touch after multi-touch - just update center for orbit
         touchState.lastCenter = {
@@ -139,6 +149,10 @@ export function useTouchControls(params: UseTouchControlsParams): void {
           x: (touchState.touches[0].clientX + touchState.touches[1].clientX) / 2,
           y: (touchState.touches[0].clientY + touchState.touches[1].clientY) / 2,
         };
+        // Reset gesture lock for new 2-finger interaction
+        touchState.twoFingerGesture = 'none';
+        touchState.gestureDistanceAccum = 0;
+        touchState.gesturePanAccum = 0;
       }
     };
 
@@ -173,11 +187,30 @@ export function useTouchControls(params: UseTouchControlsParams): void {
         const centerY = (touchState.touches[0].clientY + touchState.touches[1].clientY) / 2;
         const panDx = centerX - touchState.lastCenter.x;
         const panDy = centerY - touchState.lastCenter.y;
-        camera.pan(panDx, panDy, false);
 
         const zoomDelta = distance - touchState.lastDistance;
-        const rect = canvas.getBoundingClientRect();
-        camera.zoom(zoomDelta * 10, false, centerX - rect.left, centerY - rect.top, canvas.width, canvas.height);
+
+        // Determine dominant gesture if not yet locked
+        if (touchState.twoFingerGesture === 'none') {
+          touchState.gestureDistanceAccum += Math.abs(zoomDelta);
+          touchState.gesturePanAccum += Math.abs(panDx) + Math.abs(panDy);
+
+          // Lock gesture after enough movement (8px threshold)
+          const threshold = 8;
+          if (touchState.gestureDistanceAccum > threshold || touchState.gesturePanAccum > threshold) {
+            touchState.twoFingerGesture =
+              touchState.gestureDistanceAccum > touchState.gesturePanAccum ? 'pinch' : 'pan';
+          }
+        }
+
+        // Apply only the locked gesture
+        if (touchState.twoFingerGesture === 'pan') {
+          camera.pan(panDx, panDy, false);
+        } else if (touchState.twoFingerGesture === 'pinch') {
+          const rect = canvas.getBoundingClientRect();
+          camera.zoom(zoomDelta * 3, false, centerX - rect.left, centerY - rect.top, canvas.width, canvas.height);
+        }
+        // While gesture is 'none' (detecting), don't apply either — avoids jitter
 
         touchState.lastDistance = distance;
         touchState.lastCenter = { x: centerX, y: centerY };
@@ -192,6 +225,18 @@ export function useTouchControls(params: UseTouchControlsParams): void {
       const wasMultiTouch = touchState.multiTouch;
       touchState.touches = Array.from(e.touches);
 
+      // Multi-touch → single-touch transition: re-anchor everything to the
+      // remaining finger so the next orbit move computes a clean delta from
+      // the finger's actual position (not the stale 2-finger midpoint) and
+      // pivots under the finger (not the old pinch pivot).
+      if (previousTouchCount >= 2 && touchState.touches.length === 1) {
+        touchState.lastCenter = {
+          x: touchState.touches[0].clientX,
+          y: touchState.touches[0].clientY,
+        };
+        anchorOrbitPivotUnderFinger(touchState.touches[0]);
+      }
+
       // Only clear interaction when all fingers are lifted (gesture truly ended).
       // Clearing earlier would briefly drop interaction mode during 2-finger → 1-finger
       // transitions, triggering an expensive full-quality render mid-gesture.
@@ -229,8 +274,11 @@ export function useTouchControls(params: UseTouchControlsParams): void {
           handlePickForSelection(pickResult);
         }
 
-        // Reset multi-touch flag when all touches end
+        // Reset multi-touch and gesture lock when all touches end
         touchState.multiTouch = false;
+        touchState.twoFingerGesture = 'none';
+        touchState.gestureDistanceAccum = 0;
+        touchState.gesturePanAccum = 0;
       }
     };
 
@@ -245,16 +293,27 @@ export function useTouchControls(params: UseTouchControlsParams): void {
       touchState.multiTouch = false;
     };
 
-    canvas.addEventListener('touchstart', handleTouchStart);
-    canvas.addEventListener('touchmove', handleTouchMove);
-    canvas.addEventListener('touchend', handleTouchEnd);
+    // Use { passive: false } to ensure preventDefault() works on mobile
+    // Safari and Chrome mobile require this for smooth touch handling
+    canvas.addEventListener('touchstart', handleTouchStart, { passive: false });
+    canvas.addEventListener('touchmove', handleTouchMove, { passive: false });
+    canvas.addEventListener('touchend', handleTouchEnd, { passive: false });
     canvas.addEventListener('touchcancel', handleTouchCancel);
 
+    // Prevent iOS Safari pull-to-refresh and elastic bounce on the canvas
+    const preventOverscroll = (e: TouchEvent) => {
+      if (e.target === canvas) {
+        e.preventDefault();
+      }
+    };
+    document.addEventListener('touchmove', preventOverscroll, { passive: false });
+
     return () => {
       canvas.removeEventListener('touchstart', handleTouchStart);
       canvas.removeEventListener('touchmove', handleTouchMove);
       canvas.removeEventListener('touchend', handleTouchEnd);
       canvas.removeEventListener('touchcancel', handleTouchCancel);
+      document.removeEventListener('touchmove', preventOverscroll);
     };
   }, [isInitialized]);
 }

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" } }
+  ]
+}

package/src/hooks/federationLoadGate.test.ts

@@ -0,0 +1,90 @@
+/* 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/. */
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  acquireFederationLoadSlot,
+  releaseFederationLoadSlot,
+  __resetFederationLoadGate,
+  __getFederationLoadGateStats,
+} from './federationLoadGate.js';
+
+describe('federationLoadGate', () => {
+  beforeEach(() => {
+    __resetFederationLoadGate();
+  });
+
+  it('admits a single load immediately regardless of size', async () => {
+    const id = await acquireFederationLoadSlot(8000);
+    assert.strictEqual(__getFederationLoadGateStats().activeCount, 1);
+    releaseFederationLoadSlot(id);
+    assert.strictEqual(__getFederationLoadGateStats().activeCount, 0);
+  });
+
+  it('admits two small loads concurrently when budget allows', async () => {
+    const a = await acquireFederationLoadSlot(50);
+    const b = await acquireFederationLoadSlot(50);
+    const stats = __getFederationLoadGateStats();
+    assert.strictEqual(stats.activeCount, 2);
+    assert.strictEqual(stats.queuedCount, 0);
+    releaseFederationLoadSlot(a);
+    releaseFederationLoadSlot(b);
+  });
+
+  it('queues a second large load when the budget is full', async () => {
+    const first = await acquireFederationLoadSlot(2048);
+    let secondAcquired = false;
+    const secondPromise = acquireFederationLoadSlot(2048).then((id) => {
+      secondAcquired = true;
+      return id;
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    assert.strictEqual(secondAcquired, false);
+    assert.strictEqual(__getFederationLoadGateStats().queuedCount, 1);
+
+    releaseFederationLoadSlot(first);
+    const second = await secondPromise;
+    assert.strictEqual(secondAcquired, true);
+    releaseFederationLoadSlot(second);
+  });
+
+  it('FIFO order: first queued resolves first', async () => {
+    const blocker = await acquireFederationLoadSlot(2048);
+
+    const order: string[] = [];
+    const aPromise = acquireFederationLoadSlot(2048).then((id) => { order.push('a'); return id; });
+    const bPromise = acquireFederationLoadSlot(50).then((id) => { order.push('b'); return id; });
+
+    await new Promise((r) => setTimeout(r, 10));
+    releaseFederationLoadSlot(blocker);
+
+    const [a, b] = await Promise.all([aPromise, bPromise]);
+    assert.strictEqual(order[0], 'a');
+    releaseFederationLoadSlot(a);
+    releaseFederationLoadSlot(b);
+  });
+
+  it('release wakes multiple queued loads that fit together', async () => {
+    const blocker = await acquireFederationLoadSlot(2048);
+    const p1 = acquireFederationLoadSlot(50);
+    const p2 = acquireFederationLoadSlot(50);
+
+    await new Promise((r) => setTimeout(r, 10));
+    assert.strictEqual(__getFederationLoadGateStats().queuedCount, 2);
+
+    releaseFederationLoadSlot(blocker);
+    const [id1, id2] = await Promise.all([p1, p2]);
+    assert.strictEqual(__getFederationLoadGateStats().activeCount, 2);
+    releaseFederationLoadSlot(id1);
+    releaseFederationLoadSlot(id2);
+  });
+
+  it('treats negative file size as zero', async () => {
+    const id = await acquireFederationLoadSlot(-100);
+    assert.strictEqual(__getFederationLoadGateStats().activeCount, 1);
+    releaseFederationLoadSlot(id);
+  });
+});

package/src/hooks/federationLoadGate.ts

@@ -0,0 +1,127 @@
+/* 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/. */
+
+/**
+ * Process-wide gate for federation `addModel` calls.
+ *
+ * Two concurrent sequences (e.g. user drag-drops a second batch before the
+ * first has finished) used to multiply worker count and OOM the tab on
+ * large files. The geometry processor already caps workers per load by
+ * memory budget (`packages/geometry/src/worker-count.ts`) — but two loads
+ * each at the cap still exceed the budget together.
+ *
+ * This gate enforces a simple invariant: the *sum* of all in-flight loads
+ * fits under the same memory budget the worker count uses. When it
+ * doesn't, the new load waits in a FIFO queue until an in-flight load
+ * releases. Single-file drops never wait — only concurrent ones do.
+ *
+ * Pure-JS module, no React. Importable from anywhere; the singleton state
+ * lives on the module.
+ */
+
+interface PendingAcquire {
+  fileSizeMB: number;
+  resolve: () => void;
+}
+
+interface ActiveLoad {
+  id: number;
+  fileSizeMB: number;
+}
+
+let nextId = 1;
+const active: Map<number, ActiveLoad> = new Map();
+const queue: PendingAcquire[] = [];
+
+/**
+ * Memory cost estimate per concurrent load, in MB. Mirrors the worker-count
+ * formula at a coarser grain: input buffer (1×) + per-worker WASM
+ * (1.5×, with worker cap already applied) + accumulating meshes (1.5×) ≈ 4×.
+ */
+const COST_PER_FILE_MULTIPLIER = 4;
+
+function getDeviceMemoryGB(): number {
+  if (typeof navigator === 'undefined') return 8;
+  const dm = (navigator as unknown as { deviceMemory?: number }).deviceMemory;
+  return typeof dm === 'number' && dm > 0 ? dm : 8;
+}
+
+function getAvailableBudgetMB(): number {
+  const totalRAMmb = getDeviceMemoryGB() * 1024;
+  // Same headroom logic as worker-count.ts.
+  const reservedHeadroomMB = Math.max(1024, totalRAMmb * 0.25);
+  return Math.max(512, totalRAMmb - reservedHeadroomMB);
+}
+
+function activeCostMB(): number {
+  let sum = 0;
+  for (const load of active.values()) {
+    sum += load.fileSizeMB * COST_PER_FILE_MULTIPLIER;
+  }
+  return sum;
+}
+
+function tryAdmit(): void {
+  while (queue.length > 0) {
+    const head = queue[0];
+    const wouldCost = head.fileSizeMB * COST_PER_FILE_MULTIPLIER;
+    const available = getAvailableBudgetMB() - activeCostMB();
+    // Always admit when nothing is active (single file should never wait).
+    if (active.size === 0 || wouldCost <= available) {
+      queue.shift();
+      head.resolve();
+      // Loop continues — we may be able to admit several queued small loads
+      // after a single large load releases.
+      continue;
+    }
+    break;
+  }
+}
+
+/**
+ * Acquire a slot for a load of the given estimated size. Resolves
+ * immediately when budget allows; otherwise queues FIFO and resolves when
+ * an active load releases. Returns the slot id to pass to `release`.
+ */
+export async function acquireFederationLoadSlot(fileSizeMB: number): Promise<number> {
+  const id = nextId++;
+  const cost = Math.max(0, fileSizeMB) * COST_PER_FILE_MULTIPLIER;
+  const available = getAvailableBudgetMB() - activeCostMB();
+
+  if (active.size === 0 || cost <= available) {
+    active.set(id, { id, fileSizeMB });
+    return id;
+  }
+
+  await new Promise<void>((resolve) => {
+    queue.push({ fileSizeMB, resolve });
+  });
+  active.set(id, { id, fileSizeMB });
+  return id;
+}
+
+/**
+ * Release a previously-acquired slot. Wakes the next queued load(s) that
+ * fit in the freed budget.
+ */
+export function releaseFederationLoadSlot(id: number): void {
+  active.delete(id);
+  tryAdmit();
+}
+
+/** Internal — for tests only. Resets state. */
+export function __resetFederationLoadGate(): void {
+  active.clear();
+  queue.length = 0;
+  nextId = 1;
+}
+
+/** Internal — for tests/diagnostics. */
+export function __getFederationLoadGateStats(): { activeCount: number; queuedCount: number; activeCostMB: number } {
+  return {
+    activeCount: active.size,
+    queuedCount: queue.length,
+    activeCostMB: activeCostMB(),
+  };
+}