@ifc-lite/viewer 1.17.6 → 1.18.0

package/src/hooks/useIfcLoader.ts

@@ -281,15 +281,23 @@ export function useIfcLoader() {
         return 'IFC2X3';
       };
 
+      // Native renderer streaming path is currently disabled — the
+      // `huge native file` block further down handles real desktop
+      // streaming. This branch is retained as a scaffold for the future
+      // always-on native renderer integration.
+      const NATIVE_RENDERER_PATH_ENABLED = false as boolean;
       if (
+        NATIVE_RENDERER_PATH_ENABLED &&
         isNativeFileHandle(file) &&
-        fileName.toLowerCase().endsWith('.ifc') &&
-        false
+        fileName.toLowerCase().endsWith('.ifc')
       ) {
+        // Re-narrow `file` for the body — TS occasionally drops the
+        // type-predicate result inside a dead branch.
+        const nativeFile: NativeFileHandle = file;
         const harnessRequest = getActiveHarnessRequest();
-        const nativeCacheKey = computeNativeCacheKey(file);
-        const shouldUseNativeCache = file.size >= CACHE_SIZE_THRESHOLD;
-        const hugeNativeMode = file.size >= HUGE_NATIVE_FILE_THRESHOLD;
+        const nativeCacheKey = computeNativeCacheKey(nativeFile);
+        const shouldUseNativeCache = nativeFile.size >= CACHE_SIZE_THRESHOLD;
+        const hugeNativeMode = nativeFile.size >= HUGE_NATIVE_FILE_THRESHOLD;
         let firstBatchWaitMs: number | null = null;
         let firstVisibleGeometryMs: number | null = null;
         let modelOpenMs: number | null = null;
@@ -312,7 +320,7 @@ export function useIfcLoader() {
         let nativeGeometryCacheHit = false;
         let nativeMetadataSnapshotHit = false;
         let nativeMetadataSource: 'snapshot' | 'ifc-parse' = 'ifc-parse';
-        let nativeMetadataStartGate: 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete' = 'immediate';
+        let nativeMetadataStartGate = 'immediate' as 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete';
         let finalCoordinateInfo: CoordinateInfo | null = null;
 
         console.log(`[useIfc] Native renderer load: ${fileName}, size: ${fileSizeMB.toFixed(2)}MB`);
@@ -727,7 +735,7 @@ export function useIfcLoader() {
         let fullNativeDataStore: IfcDataStore | null = null;
         let nativeLoadStage: 'open' | 'streamGeometry' | 'finalizeGeometry' | 'hydrateMetadata' | 'complete' = 'open';
         let nativeMetadataSource: 'snapshot' | 'ifc-parse' = 'ifc-parse';
-        let nativeMetadataStartGate: 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete' = 'immediate';
+        let nativeMetadataStartGate = 'immediate' as 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete';
 
         setGeometryResult(null);
 
@@ -1638,8 +1646,10 @@ export function useIfcLoader() {
       }
 
       // Try server parsing first (enabled by default for multi-core performance)
-      // Only for IFC4 STEP files (server doesn't support IFCX)
-      if (format === 'ifc' && USE_SERVER && SERVER_URL && SERVER_URL !== '') {
+      // Only for IFC4 STEP files (server doesn't support IFCX). Native
+      // file handles (Tauri) don't have an HTTP-uploadable body, so skip
+      // the server path and fall through to the WASM loader.
+      if (format === 'ifc' && USE_SERVER && SERVER_URL && SERVER_URL !== '' && !isNativeFileHandle(file)) {
         // Pass buffer directly - server uses File object for parsing, buffer is only for size checks
         const serverSuccess = await loadFromServer(file, buffer, () => loadSessionRef.current !== currentSession);
         if (serverSuccess) {
@@ -1792,7 +1802,9 @@ export function useIfcLoader() {
           if (geometryIteratorClosed || typeof geometryIterator.return !== 'function') return;
           geometryIteratorClosed = true;
           try {
-            await geometryIterator.return();
+            // `AsyncIterator.return()` is signed as taking a value in
+            // current TS libs; callers conventionally pass `undefined`.
+            await geometryIterator.return(undefined);
           } catch {
             // Ignore iterator shutdown failures during recovery.
           }

package/src/hooks/useKeyboardShortcuts.ts

@@ -88,6 +88,10 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       e.preventDefault();
       setActiveTool('section');
     }
+    if (key === 'p' && !ctrl && !shift) {
+      e.preventDefault();
+      setActiveTool('annotate');
+    }
 
     // Basket controls (automatic context source)
     // I = Isolate from current context
@@ -150,6 +154,26 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       resetVisibilityForHomeFromStore();
     }
 
+    // Add-element tool shortcuts — Enter commits an in-progress slab
+    // polygon; Esc clears any pending points before falling through to
+    // the global Esc handler (which exits the tool).
+    if (activeTool === 'addElement') {
+      const state = useViewerStore.getState();
+      const polygonable = ['slab', 'roof', 'plate', 'space'].includes(state.addElementType);
+      if (key === 'enter' && polygonable && state.addElementSlabMode === 'polygon') {
+        e.preventDefault();
+        // Lazy import keeps this module out of the keyboard hook's
+        // synchronous bundle (the close handler pulls in toast).
+        import('@/components/viewer/selectionHandlers').then((mod) => mod.commitAddElementSlabPolygon());
+        return;
+      }
+      if (key === 'escape' && state.addElementPendingPoints.length > 0) {
+        e.preventDefault();
+        state.clearAddElementPending();
+        return;
+      }
+    }
+
     // Measure tool shortcuts
     if (activeTool === 'measure') {
       // Cancel active measurement with ESC
@@ -243,6 +267,7 @@ export const KEYBOARD_SHORTCUTS = [
   { key: 'V', description: 'Select tool', category: 'Tools' },
   { key: 'C', description: 'Walk mode', category: 'Tools' },
   { key: 'M', description: 'Measure tool', category: 'Tools' },
+  { key: 'P', description: 'Annotate tool — drop a pin with a note', category: 'Tools' },
   { key: 'X', description: 'Section tool', category: 'Tools' },
   { key: 'S', description: 'Toggle snapping (Measure tool)', category: 'Tools' },
   { key: 'Esc', description: 'Cancel measurement (Measure tool)', category: 'Tools' },

package/src/hooks/useSandbox.ts

@@ -165,7 +165,7 @@ export function useSandbox(config?: SandboxConfig) {
       // Create a fresh sandbox for every execution — full isolation
       const { createSandbox } = await import('@ifc-lite/sandbox');
       sandbox = await createSandbox(bim, {
-        permissions: { model: true, query: true, viewer: true, mutate: true, lens: true, export: true, files: true, ...config?.permissions },
+        permissions: { model: true, query: true, viewer: true, mutate: true, store: true, lens: true, export: true, files: true, ...config?.permissions },
         limits: { timeoutMs: 30_000, ...config?.limits },
       });
       activeSandboxRef.current = sandbox;

package/src/hooks/useSearchIndex.ts

@@ -0,0 +1,125 @@
+/* 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/. */
+
+/**
+ * useSearchIndex — lazy builder for the Tier-1 search index.
+ *
+ * Mount once near the root of the viewer shell (currently `SearchInline`,
+ * since it's always rendered once the toolbar is up). The hook watches
+ * the federated `models` map; for each model with a populated
+ * `ifcDataStore` that doesn't yet have a Tier-1 record, it spawns a
+ * chunked build. Models that disappear get their index record dropped.
+ *
+ * Load-perf guarantee: the build NEVER runs during the actual IFC load
+ * because `ifcDataStore` is non-null only after the parser reports the
+ * model is ready (`onSpatialReady` + geometry). The build itself yields
+ * to the event loop every `DEFAULT_CHUNK_SIZE` rows so a 4M-entity
+ * index doesn't hog the main thread.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useShallow } from 'zustand/react/shallow';
+import { useViewerStore } from '@/store';
+import { buildTier1Index } from '@/lib/search/tier1-index';
+
+export function useSearchIndex(): void {
+  const {
+    models,
+    searchIndexes,
+    setSearchIndexRecord,
+    removeSearchIndexRecord,
+    searchFilterSchema,
+    removeFilterSchema,
+  } = useViewerStore(
+    useShallow((s) => ({
+      models: s.models,
+      searchIndexes: s.searchIndexes,
+      setSearchIndexRecord: s.setSearchIndexRecord,
+      removeSearchIndexRecord: s.removeSearchIndexRecord,
+      searchFilterSchema: s.searchFilterSchema,
+      removeFilterSchema: s.removeFilterSchema,
+    })),
+  );
+
+  // One AbortController per in-flight build. Lets us cancel cleanly when a
+  // model is removed mid-build or when the component unmounts.
+  const controllersRef = useRef<Map<string, AbortController>>(new Map());
+
+  useEffect(() => {
+    const controllers = controllersRef.current;
+
+    // Drop records / abort builds for models that no longer exist.
+    for (const modelId of Array.from(searchIndexes.keys())) {
+      if (!models.has(modelId)) {
+        controllers.get(modelId)?.abort();
+        controllers.delete(modelId);
+        removeSearchIndexRecord(modelId);
+      }
+    }
+
+    // Drop the filter-schema cache for departed models too. Stale entries
+    // would surface in the chip dropdowns the next time a model with the
+    // same id loaded (e.g. user reopens a different file as model_0).
+    for (const modelId of Array.from(searchFilterSchema.keys())) {
+      if (!models.has(modelId)) removeFilterSchema(modelId);
+    }
+
+    // Kick off builds for models that are loaded but not yet indexed.
+    for (const [modelId, model] of models) {
+      if (!model.ifcDataStore) continue;
+      const existing = searchIndexes.get(modelId);
+      if (existing && existing.status !== 'pending') continue;
+      if (controllers.has(modelId)) continue;
+
+      const controller = new AbortController();
+      controllers.set(modelId, controller);
+
+      setSearchIndexRecord(modelId, { status: 'building', progress: 0 });
+
+      // Fire-and-forget — the build is cancellable via the controller, and
+      // the completion handlers update the store without needing a ref.
+      void buildTier1Index(modelId, model.ifcDataStore, {
+        signal: controller.signal,
+        onProgress: (done, total) => {
+          if (controller.signal.aborted) return;
+          const progress = total > 0 ? done / total : 1;
+          setSearchIndexRecord(modelId, { status: 'building', progress });
+        },
+      })
+        .then((index) => {
+          if (controller.signal.aborted) return;
+          controllers.delete(modelId);
+          setSearchIndexRecord(modelId, { status: 'ready', index, progress: 1 });
+        })
+        .catch((err: unknown) => {
+          controllers.delete(modelId);
+          if (err instanceof DOMException && err.name === 'AbortError') return;
+          const message = err instanceof Error ? err.message : String(err);
+          // Don't set a 'ready' record — Tier-0 fallback stays live.
+          console.warn(`[useSearchIndex] build failed for ${modelId}:`, message);
+          setSearchIndexRecord(modelId, { status: 'error', error: message });
+        });
+    }
+
+    // On unmount OR next effect pass, abort everything. The effect re-runs
+    // only when `models` / `searchIndexes` changes, so steady-state
+    // incurs no abort — the `controllers.has(modelId)` guard above makes
+    // re-entry idempotent.
+    return () => {
+      // Intentionally NOT aborting everything on every re-render — only
+      // models that went missing got aborted above. The real cleanup is
+      // the component-unmount pass below.
+    };
+  }, [models, searchIndexes, setSearchIndexRecord, removeSearchIndexRecord, searchFilterSchema, removeFilterSchema]);
+
+  // Abort any in-flight builds when the consumer unmounts. Separate effect
+  // so it only fires on unmount (no deps).
+  useEffect(() => {
+    const controllers = controllersRef.current;
+    return () => {
+      for (const c of controllers.values()) c.abort();
+      controllers.clear();
+    };
+  }, []);
+}

package/src/index.css

@@ -379,6 +379,43 @@ body {
   color: var(--color-primary) !important;
 }
 
+/* Raw STEP tab — terminal-flavoured dev affordance.
+   Compact (icon-only </>), separates visually from the three "human"
+   tabs with a left divider and a green active state that nods to a
+   shell cursor. Stays width-stable at narrow panel widths because
+   it explicitly opts out of `flex: 1` (uses an `auto`-ish width
+   driven by the </> glyph plus padding). */
+.properties-tab-trigger.raw-step-tab-trigger {
+  flex: 0 0 auto;
+  min-width: 2.25rem;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+  border-left: 1px solid var(--tabs-border);
+  letter-spacing: 0;
+  color: color-mix(in srgb, var(--tab-text) 70%, transparent) !important;
+}
+
+.properties-tab-trigger.raw-step-tab-trigger:hover {
+  background-color: color-mix(in srgb, #10b981 16%, var(--tabs-bg)) !important;
+  color: #047857 !important;
+}
+
+.dark .properties-tab-trigger.raw-step-tab-trigger:hover {
+  background-color: color-mix(in srgb, #10b981 22%, var(--tabs-bg)) !important;
+  color: #34d399 !important;
+}
+
+.properties-tab-trigger.raw-step-tab-trigger[data-state="active"] {
+  background-color: color-mix(in srgb, #10b981 14%, var(--tab-active-bg)) !important;
+  color: #047857 !important;
+  border-top-color: #10b981 !important;
+}
+
+.dark .properties-tab-trigger.raw-step-tab-trigger[data-state="active"] {
+  color: #34d399 !important;
+  border-top-color: #34d399 !important;
+}
+
 /* Quantity cards - cyan accent */
 .dark .border-blue-200,
 .dark .border-blue-800,
@@ -997,6 +1034,35 @@ body {
   cursor: not-allowed;
 }
 
+/* Annotation pin idle introduction — fires once on mount, then settles.
+   Driven by a `prefers-reduced-motion` guard so accessibility users
+   don't get hit by the pulse. */
+@keyframes annotation-pin-idle {
+  0% {
+    transform: scale(0.7);
+    box-shadow: 0 0 0 0 rgba(245, 158, 11, 0.55);
+  }
+  60% {
+    transform: scale(1.08);
+    box-shadow: 0 0 0 8px rgba(245, 158, 11, 0);
+  }
+  100% {
+    transform: scale(1);
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35),
+      0 0 0 1px rgba(0, 0, 0, 0.15);
+  }
+}
+
+.annotation-pin-idle {
+  animation: annotation-pin-idle 360ms cubic-bezier(0.4, 0, 0.2, 1) forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .annotation-pin-idle {
+    animation: none;
+  }
+}
+
 /* Loading skeleton animation */
 @keyframes skeleton-pulse {
   0%, 100% {

package/src/lib/llm/system-prompt.test.ts

@@ -91,6 +91,20 @@ test('system prompt includes selected entity IFC context when provided', () => {
   assert.match(prompt, /Selected entities: Tower: IfcCurtainWall "Facade Panel A", kind=occurrence, storey=Level 10@31.5m, psets=Pset_CurtainWallCommon, typePsets=Pset_CurtainWallTypeCommon, qsets=Qto_CurtainWallBaseQuantities, material=Aluminium, classifications=A-123 \| Tower: IfcWallType "Exterior Wall Type", kind=type, psets=Pset_WallCommon, classifications=A-WALL/);
 });
 
+test('system prompt includes the BIM.STORE cheat sheet and routing rule', () => {
+  const prompt = buildSystemPrompt();
+
+  // Section heading + the three method examples
+  assert.match(prompt, /## BIM\.STORE CHEAT SHEET/);
+  assert.match(prompt, /bim\.store\.setPositionalAttribute\(profile, 3, 0\.6\)/);
+  assert.match(prompt, /bim\.store\.addEntity\("arch"/);
+  assert.match(prompt, /bim\.store\.removeEntity\(unwantedRef\)/);
+
+  // Routing rule disambiguating store / mutate / create
+  assert.match(prompt, /bim\.store\.setPositionalAttribute\(entity, index, value\)`? for positional STEP-argument edits/);
+  assert.match(prompt, /Do NOT use `bim\.create` for these/);
+});
+
 test('system prompt includes method-specific create contract guidance', () => {
   const prompt = buildSystemPrompt();
   assert.match(prompt, /BIM\.CREATE CONTRACT CHEAT SHEET/);

package/src/lib/llm/system-prompt.ts

@@ -100,6 +100,69 @@ function buildIntentMethodSection(intent: LlmTaskIntent): string {
   return lines.join('\n');
 }
 
+function buildStoreCheatSheet(): string {
+  const storeNamespace = NAMESPACE_SCHEMAS.find((schema) => schema.name === 'store');
+  if (!storeNamespace) return '';
+
+  return [
+    '## BIM.STORE CHEAT SHEET',
+    '`bim.store.*` edits a parsed model in place — use it when the user already has',
+    'a model loaded and wants raw STEP-level edits, NOT when building a new model from',
+    'scratch (that\'s `bim.create`).',
+    '',
+    '- `addEntity(modelId, { type, attributes })` — inject a STEP entity. `attributes`',
+    '  follows EntityExtractor output: numbers → REAL/integer, `"#42"` → ref, `".AREA."` → enum,',
+    '  `null` → `$`, arrays → STEP list. Returns `{ modelId, expressId }`.',
+    '- `removeEntity(entity)` — tombstones existing source entities or forgets overlay-only ones.',
+    '- `setPositionalAttribute(entity, index, value)` — edit a non-IfcRoot attribute by',
+    '  zero-based STEP argument index. Use this for `IfcRectangleProfileDef.XDim` (index 3),',
+    '  `YDim` (index 4), `IfcCartesianPoint.Coordinates` (index 0), etc. Use `bim.mutate.setAttribute`',
+    '  for IfcRoot attributes (Name, Description, ObjectType, Tag).',
+    '- High-level builders anchor a new element to an existing IfcBuildingStorey:',
+    '    `addColumn(modelId, storeyId, { Position, Width, Depth, Height })`',
+    '    `addWall(modelId, storeyId, { Start, End, Thickness, Height })`',
+    '    `addBeam(modelId, storeyId, { Start, End, Width, Height })`',
+    '    `addSlab(modelId, storeyId, { Position, Width, Depth, Thickness })`             // rectangle',
+    '    `addSlab(modelId, storeyId, { Profile: "polygon", OuterCurve: [[x,y],…], Thickness })`',
+    '    `addRoof(modelId, storeyId, { … same shape as addSlab — emits .FLAT_ROOF. })`',
+    '    `addPlate(modelId, storeyId, { … same shape as addSlab — IfcPlate, PredefinedType? })`',
+    '    `addSpace(modelId, storeyId, { Position, Width, Depth, Height, LongName? })`     // room rectangle',
+    '    `addSpace(modelId, storeyId, { Profile: "polygon", OuterCurve, Height })`        // room polygon',
+    '    `addDoor(modelId, storeyId, { Position, Width, Height, FrameThickness?, OperationType? })`',
+    '    `addWindow(modelId, storeyId, { Position, Width, Height, FrameThickness?, PartitioningType? })`',
+    '    `addMember(modelId, storeyId, { Start, End, Width, Height, PredefinedType? })`   // brace/post/strut',
+    '  Each emits ~12 STEP entities (placement chain → profile → solid → representation +',
+    '  IfcRelContainedInSpatialStructure, except `addSpace` which uses IfcRelAggregates).',
+    '  Coords are storey-local metres. Polygon outlines need ≥3 points; the polyline is auto-closed.',
+    '- Edits accumulate in an overlay; they show up after `bim.export.ifc(bim.query.all())`',
+    '  or when the viewer next renders. Use `bim.mutate.undo(modelId)` to roll back.',
+    '',
+    'Canonical examples:',
+    '```js',
+    '// Resize a rectangular profile from 0.3×0.4 to 0.6×0.4',
+    'const profile = bim.query.byId("arch", 35);',
+    'bim.store.setPositionalAttribute(profile, 3, 0.6);   // XDim',
+    '',
+    '// Drop a wall on the first storey',
+    'const storeyId = bim.query.byType("IfcBuildingStorey")[0].ref.expressId;',
+    'bim.store.addWall("arch", storeyId, {',
+    '  Start: [0, 0, 0], End: [5, 0, 0],',
+    '  Thickness: 0.2, Height: 3, Name: "North Wall",',
+    '});',
+    '',
+    '// Add a custom IfcCartesianPoint, then reference it from another entity',
+    'const pt = bim.store.addEntity("arch", {',
+    '  type: "IfcCartesianPoint",',
+    '  attributes: [[1.0, 2.0, 0.0]],',
+    '});',
+    'console.log("Allocated", pt.expressId);',
+    '',
+    '// Drop an entity entirely',
+    'bim.store.removeEntity(unwantedRef);',
+    '```',
+  ].join('\n');
+}
+
 function buildCreateContractCheatSheet(): string {
   const createNamespace = NAMESPACE_SCHEMAS.find((schema) => schema.name === 'create');
   if (!createNamespace) return '## BIM.CREATE CONTRACT CHEAT SHEET';
@@ -280,6 +343,7 @@ export function buildSystemPrompt(
   const intent = inferPromptIntent(task);
   const intentSection = buildIntentMethodSection(intent);
   const createContractCheatSheet = buildCreateContractCheatSheet();
+  const storeCheatSheet = buildStoreCheatSheet();
   const placementSemantics = buildPlacementSemanticsSection();
   const inspectionGuidance = buildInspectionGuidance();
 
@@ -326,9 +390,11 @@ ${intentSection}
 4. Keep scripts concise — avoid unnecessary abstractions
 5. Coordinates are in meters. Z is up. Do NOT assume every create method is storey-relative — use the method-specific placement rules below.
 6. For create or explicit rewrite turns, wrap runnable code in a \`\`\`js\`\`\` fence. For repair turns, return exactly one \`\`\`ifc-script-edits\`\`\` fence containing SEARCH/REPLACE blocks and no \`\`\`js\`\`\` fence.
-7. If the user asks to modify existing data, use \`bim.mutate\` or \`bim.query\` — NOT \`bim.create\`
+7. If the user asks to modify existing data, use \`bim.mutate\`, \`bim.store\`, or \`bim.query\` — NOT \`bim.create\`
    - Use \`bim.mutate.setAttribute(entity, "Description", "...")\` for root IFC attributes like \`Name\`, \`Description\`, \`ObjectType\`, or \`Tag\`
    - Use \`bim.mutate.setProperty(entity, "Pset_Name", "PropName", value)\` only for IfcPropertySet or quantity data
+   - Use \`bim.store.setPositionalAttribute(entity, index, value)\` for positional STEP-argument edits (profile dimensions, \`IfcCartesianPoint.Coordinates\`, and other index-addressed attributes — even when they have a symbolic name) — see BIM.STORE CHEAT SHEET
+   - Use \`bim.store.addEntity\` / \`bim.store.removeEntity\` to inject or drop raw STEP entities in an already-loaded model. Do NOT use \`bim.create\` for these — \`bim.create\` builds a fresh project
    - Distinguish occurrence vs type edits: occurrence/entity-specific changes belong on the occurrence; shared defaults and inherited type properties belong on the related \`Ifc...Type\` entity
    - If CURRENT MODEL STATE marks a selection as \`kind=type\`, treat it as a type object and avoid describing it as one physical placed occurrence
    - When an occurrence is selected, inspect \`bim.query.typeProperties(entity)\` before editing inherited values; mutate the type entity when the intent is to change all occurrences that share that type
@@ -353,6 +419,8 @@ ${intentSection}
 
 ${createContractCheatSheet}
 
+${storeCheatSheet}
+
 ${placementSemantics}
 - \`addIfcDoor\` and \`addIfcWindow\` do not infer host-wall orientation. If you place them next to angled walls, they will stay world-aligned unless you build the wall void another way.
 - For storey-relative methods, \`Z=0\` usually means floor level of that storey.
@@ -393,6 +461,39 @@ for (let i = 0; i < storeyCount; i++) {
 - If repeated elements appear only at one level, you probably reused one storey reference instead of iterating over the intended storeys.
 - If repeated world-placement elements stack at the base level, first check whether their Z coordinates include the current storey elevation.
 
+## SCHEDULING / 4D (IfcTask, IfcWorkSchedule, IfcRelSequence)
+- ifc-lite ships a Gantt panel in the lower workspace that plays a construction-sequence animation driven by IfcTask dates and the products each task controls.
+- Creating a schedule from scratch:
+  \`\`\`js
+  const h = bim.create.project({ Name: "Demo" });
+  const storey = bim.create.addIfcBuildingStorey(h, { Name: "Ground", Elevation: 0 });
+  const wallA = bim.create.addIfcWall(h, storey, { Start: [0,0,0], End: [5,0,0], Thickness: 0.2, Height: 3 });
+
+  const schedule = bim.create.addIfcWorkSchedule(h, {
+    Name: "Construction schedule",
+    StartTime: "2024-05-01T08:00:00",
+    FinishTime: "2024-06-30T17:00:00",
+    PredefinedType: "PLANNED",
+  });
+  const task = bim.create.addIfcTask(h, {
+    Name: "Install wall A",
+    PredefinedType: "INSTALLATION",
+    ScheduleStart: "2024-05-06T08:00:00",
+    ScheduleFinish: "2024-05-10T17:00:00",
+    ScheduleDuration: "P5D",
+  });
+  bim.create.assignTasksToWorkSchedule(h, schedule, [task]);
+  bim.create.assignProductsToTask(h, task, [wallA]);   // products reveal in the 4D animation
+  // bim.create.addIfcRelSequence(h, prevTask, task, { SequenceType: "FINISH_START", TimeLag: "P2D" });
+  // bim.create.nestTasks(h, summaryTask, [task]);    // WBS hierarchy
+  \`\`\`
+- Dates are ISO 8601 (\`2024-05-01T08:00:00\`). Durations are ISO 8601 (\`P5D\`, \`PT8H\`).
+- IfcTask.PredefinedType is an enum — prefer CONSTRUCTION, INSTALLATION, DEMOLITION, RENOVATION over free strings.
+- For milestones (e.g. "handover"), set \`IsMilestone: true\` and omit or equate start/finish.
+- \`assignProductsToTask\` is the bridge that lets the 4D Gantt animation reveal/hide elements as time advances. Always bind tasks to the elements they construct when the user wants the viewport to animate.
+- Reading an existing schedule: \`bim.schedule.data()\` returns { workSchedules, tasks, sequences }. Use it to inspect or validate a construction plan.
+- **CSV / Excel / PDF → schedule workflow:** when the user attaches a spreadsheet or PDF with activities and dates, parse it with \`bim.files.csv(name)\` (for CSV) or \`bim.files.text(name)\` (for text-extracted PDF/Excel content converted upstream). Map each row to an \`addIfcTask(...)\` call and resolve the \`products\` column — an IFC type like \`IfcWall\` expands to every matching entity, a globalId maps to one specific entity — into \`expressId\`s to feed \`assignProductsToTask\`. The \`Construction schedule (4D)\` script template is a ready-made starting point.
+
 ## API REFERENCE
 ${apiRef}
 

package/src/lib/llm/types.ts

@@ -124,6 +124,12 @@ export interface FileAttachment {
   imageBase64?: string;
   /** Whether this is an image attachment */
   isImage?: boolean;
+  /** Base64-encoded PDF data (for PDF attachments — Anthropic native document blocks) */
+  pdfBase64?: string;
+  /** Whether this is a PDF attachment */
+  isPdf?: boolean;
+  /** Whether this is a binary spreadsheet (xlsx/xls/ods) that we can't parse here yet. */
+  isSpreadsheetBinary?: boolean;
 }
 
 export type ModelTier = 'free' | 'byok';

package/src/lib/recent-files.ts

@@ -24,8 +24,21 @@ export interface RecentFileEntry {
   name: string;
   size: number;
   timestamp: number;
+  /** Native filesystem path (Tauri only) — enables direct re-open from disk. */
+  path?: string;
+  /** Last-modified epoch in ms when known (Tauri stat). */
+  modifiedMs?: number | null;
 }
 
+// Input shape for `recordRecentFiles` — accepts the optional native fields
+// so callers can persist a path / modifiedMs without lying about the type.
+export type RecentFileInput = {
+  name: string;
+  size: number;
+  path?: string;
+  modifiedMs?: number | null;
+};
+
 // ── localStorage (metadata) ─────────────────────────────────────────────
 
 export function getRecentFiles(): RecentFileEntry[] {
@@ -33,17 +46,30 @@ export function getRecentFiles(): RecentFileEntry[] {
   catch { return []; }
 }
 
-export function recordRecentFiles(files: { name: string; size: number }[]) {
+// Path-aware dedup key: when a native filesystem path is available it
+// uniquely identifies the file (so `A/model.ifc` and `B/model.ifc` are
+// kept separate); otherwise fall back to the name (browser uploads
+// don't expose paths).
+function recentKey(f: { name: string; path?: string }): string {
+  return f.path ? `path:${f.path}` : `name:${f.name}`;
+}
+
+export function recordRecentFiles(files: RecentFileInput[]) {
   try {
-    const names = new Set(files.map(f => f.name));
-    const existing = getRecentFiles().filter(f => !names.has(f.name));
+    const incomingKeys = new Set(files.map(recentKey));
+    const existing = getRecentFiles().filter(f => !incomingKeys.has(recentKey(f)));
     const entries: RecentFileEntry[] = files.map(f => ({
       name: f.name,
       size: f.size,
       timestamp: Date.now(),
+      path: f.path,
+      modifiedMs: f.modifiedMs ?? null,
     }));
     localStorage.setItem(KEY, JSON.stringify([...entries, ...existing].slice(0, 10)));
-  } catch { /* noop */ }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('[recent-files] failed to persist recent files metadata', err);
+  }
 }
 
 /** Format bytes into human-readable size */
@@ -104,6 +130,14 @@ export async function cacheFileBlobs(files: File[]): Promise<void> {
 
 /** Retrieve a cached file blob and reconstruct a File object. */
 export async function getCachedFile(target: string | RecentFileEntry): Promise<File | null> {
+  // Path-bearing entries (Tauri filesystem) are uniquely keyed by path
+  // in the recents list, but the IndexedDB cache is name-keyed. A
+  // name-only hit could resolve `A/model.ifc` to the cached blob from
+  // `B/model.ifc`, opening the wrong file silently. Defer to the
+  // caller's native re-open path instead.
+  if (typeof target !== 'string' && target.path) {
+    return null;
+  }
   const name = typeof target === 'string' ? target : target.name;
   try {
     const db = await openDB();