@ifc-lite/viewer 1.14.2 → 1.14.4

package/src/hooks/useSandbox.ts

@@ -14,6 +14,12 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useBim } from '../sdk/BimProvider.js';
 import { useViewerStore } from '../store/index.js';
 import type { Sandbox, ScriptResult, SandboxConfig } from '@ifc-lite/sandbox';
+import { validateScriptPreflightDetailed } from '../lib/llm/script-preflight.js';
+import {
+  createRuntimeDiagnostic,
+  formatDiagnosticsForDisplay,
+  type RuntimeScriptDiagnostic,
+} from '../lib/llm/script-diagnostics.js';
 
 /** Type guard for ScriptError shape (has logs + durationMs) */
 function isScriptError(err: unknown): err is { message: string; logs: Array<{ level: string; args: unknown[]; timestamp: number }>; durationMs: number } {
@@ -27,6 +33,101 @@ function isScriptError(err: unknown): err is { message: string; logs: Array<{ le
   );
 }
 
+function augmentScriptError(message: string, code?: string): { message: string; diagnostics: RuntimeScriptDiagnostic[] } {
+  const lower = message.toLowerCase();
+  const source = code ?? '';
+  const missingIdent = /['"]([A-Za-z_]\w*)['"] is not defined/i.exec(message)?.[1];
+  const looksDetachedCreateSnippet = /\bbim\.create\.[A-Za-z]+\(\s*h\s*,/.test(source)
+    && !/\b(?:const|let|var)\s+h\b/.test(source)
+    && !/bim\.create\.project\(/.test(source);
+  const looksWorldPlacementScript = /\bbim\.create\.(addIfcCurtainWall|addIfcMember|addIfcPlate)\(/.test(source)
+    && /\baddIfcBuildingStorey\(/.test(source)
+    && /\bconst\s+elevation\b|\bz\s*=/.test(source);
+
+  if (lower.includes(`can't access property "location", placement is undefined`)) {
+    const diagnostic = createRuntimeDiagnostic(
+      'generic_placement_contract',
+      'Likely cause: a generic `bim.create.addElement(...)` payload is using `Position` or missing `Placement.Location`. Use `Placement: { Location: [x, y, z] }` and `Depth`.',
+      'error',
+      { methodName: 'addElement', symbol: 'Placement.Location', fixHint: 'Use `Placement: { Location: [...] }` and include `Depth`.' },
+    );
+    return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+  }
+  if (lower.includes('invalid creator handle')) {
+    const diagnostic = createRuntimeDiagnostic(
+      'generic_placement_contract',
+      'Likely cause: the script finalized or invalidated the active creator handle before later create calls completed. Move `bim.create.toIfc(h)` to the end and do not reuse a finalized handle.',
+      'error',
+      {
+        symbol: 'h',
+        failureKind: 'creator_lifecycle',
+        rootCauseKey: 'creator_lifecycle_violation',
+        repairScope: 'structural',
+        fixHint: 'Finalize the model only once, after all create calls are done.',
+      },
+    );
+    return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+  }
+  if (lower.includes(`can't access property "tostring", v is undefined`)) {
+    if (/\bbim\.create\.addIfcPlate\(/.test(source) && /\bHeight\s*:/.test(source) && !/\bDepth\s*:/.test(source)) {
+      const diagnostic = createRuntimeDiagnostic(
+        'plate_contract_mismatch',
+        'Likely cause: `bim.create.addIfcPlate(...)` was given slab-style keys. Re-check the plate contract and use `Position`, `Width`, `Depth`, and `Thickness` instead of `Height`.',
+        'error',
+        { methodName: 'addIfcPlate', symbol: 'Height', fixHint: 'Use `Position`, `Width`, `Depth`, and `Thickness` for plates.' },
+      );
+      return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+    }
+    if (looksWorldPlacementScript) {
+      const diagnostic = createRuntimeDiagnostic(
+        'world_placement_elevation',
+        'Likely cause: a repeated world-placement method (such as `addIfcCurtainWall(...)`, `addIfcMember(...)`, or `addIfcPlate(...)`) is missing the current level elevation in its Z coordinates. These methods do not inherit storey-relative Z automatically.',
+        'error',
+        {
+          failureKind: 'world_placement',
+          repairScope: 'block',
+          fixHint: 'Include the current level/storey elevation in `Start`, `End`, or `Position` Z coordinates.',
+        },
+      );
+      return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+    }
+    return {
+      message: `${message}\nLikely cause: a required numeric geometry field is missing or undefined (commonly \`Elevation\`, \`Width\`, \`Depth\`, \`Height\`, or \`Thickness\`). Re-check the exact required keys for the create method you called.`,
+      diagnostics: [],
+    };
+  }
+  if (lower.includes(`'position' is not defined`) || lower.includes(`"position" is not defined`)) {
+    return {
+      message: `${message}\nLikely cause: the script contains a malformed BIM object literal or transpilation fallback corrupted a plain JS key like \`Position: [...]\`. Re-send the exact object with explicit key-value pairs.`,
+      diagnostics: [],
+    };
+  }
+  if (missingIdent && ['h', 'storey', 'width', 'depth', 'i', 'z'].includes(missingIdent) && looksDetachedCreateSnippet) {
+    const diagnostic = createRuntimeDiagnostic(
+      'detached_snippet_scope',
+      `Likely cause: the fix replaced the full script with a detached fragment that still depends on outer variables like \`${missingIdent}\`. Preserve the surrounding project/storey/loop context and patch the existing script in place.`,
+      'error',
+      {
+        symbol: missingIdent,
+        failureKind: 'detached_snippet',
+        repairScope: 'structural',
+        fixHint: 'Patch the existing script instead of returning a smaller fragment.',
+      },
+    );
+    return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+  }
+  if (lower.includes('rotated') && lower.includes('window') && lower.includes('wall')) {
+    const diagnostic = createRuntimeDiagnostic(
+      'wall_hosted_opening_alignment',
+      'Likely cause: a standalone `bim.create.addIfcWindow(...)` was used where a wall-hosted insert was needed. Use `bim.create.addIfcWallWindow(...)` or wall `Openings` for wall-aligned placement.',
+      'error',
+      { methodName: 'addIfcWindow', fixHint: 'Use `addIfcWallWindow(...)` or wall `Openings` for wall-aligned placement.' },
+    );
+    return { message: `${message}\n${diagnostic.message}`, diagnostics: [diagnostic] };
+  }
+  return { message, diagnostics: [] };
+}
+
 /**
  * Hook that provides a sandbox execution interface.
  *
@@ -41,18 +142,30 @@ export function useSandbox(config?: SandboxConfig) {
   const setExecutionState = useViewerStore((s) => s.setScriptExecutionState);
   const setResult = useViewerStore((s) => s.setScriptResult);
   const setError = useViewerStore((s) => s.setScriptError);
+  const setDiagnostics = useViewerStore((s) => s.setScriptDiagnostics);
 
   /** Execute a script in an isolated sandbox context */
   const execute = useCallback(async (code: string): Promise<ScriptResult | null> => {
     setExecutionState('running');
     setError(null);
+    setDiagnostics([]);
+
+    const preflightDiagnostics = validateScriptPreflightDetailed(code);
+    if (preflightDiagnostics.length > 0) {
+      const preflightErrors = formatDiagnosticsForDisplay(preflightDiagnostics);
+      setError(
+        `Preflight validation failed:\n${preflightErrors.map((e) => `- ${e}`).join('\n')}`,
+        preflightDiagnostics,
+      );
+      return null;
+    }
 
     let sandbox: Sandbox | null = null;
     try {
       // 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, ...config?.permissions },
+        permissions: { model: true, query: true, viewer: true, mutate: true, lens: true, export: true, files: true, ...config?.permissions },
         limits: { timeoutMs: 30_000, ...config?.limits },
       });
       activeSandboxRef.current = sandbox;
@@ -65,10 +178,11 @@ export function useSandbox(config?: SandboxConfig) {
       });
       return result;
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      setError(message);
+      const runtime = augmentScriptError(err instanceof Error ? err.message : String(err), code);
 
-      // If the error is a ScriptError with captured logs, preserve them
+      // If the error is a ScriptError with captured logs, preserve them.
+      // Important: setError must run AFTER setResult, because setResult clears
+      // scriptLastError in the store.
       if (isScriptError(err)) {
         setResult({
           value: undefined,
@@ -76,6 +190,7 @@ export function useSandbox(config?: SandboxConfig) {
           durationMs: err.durationMs,
         });
       }
+      setError(runtime.message, runtime.diagnostics);
       return null;
     } finally {
       // Always dispose the sandbox after execution
@@ -86,7 +201,7 @@ export function useSandbox(config?: SandboxConfig) {
         activeSandboxRef.current = null;
       }
     }
-  }, [bim, config?.permissions, config?.limits, setExecutionState, setResult, setError]);
+  }, [bim, config?.permissions, config?.limits, setDiagnostics, setExecutionState, setResult, setError]);
 
   /** Reset clears any active sandbox (no-op if none running) */
   const reset = useCallback(() => {
@@ -97,7 +212,8 @@ export function useSandbox(config?: SandboxConfig) {
     setExecutionState('idle');
     setResult(null);
     setError(null);
-  }, [setExecutionState, setResult, setError]);
+    setDiagnostics([]);
+  }, [setDiagnostics, setExecutionState, setResult, setError]);
 
   // Cleanup on unmount
   useEffect(() => {

package/src/index.css

@@ -528,3 +528,13 @@ body {
   border-radius: 0.25rem;
   animation: skeleton-pulse 2s ease-in-out infinite;
 }
+
+/* Clerk overlays (billing/sidebar/modal) should always stack above app overlays. */
+.cl-portalRoot,
+.cl-modalBackdrop,
+.cl-modalContent,
+.cl-drawerRoot,
+.cl-drawerBackdrop,
+.cl-drawerContent {
+  z-index: 100000 !important;
+}

package/src/lib/attachments.ts

@@ -0,0 +1,46 @@
+/* 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 type { ChatMessage, FileAttachment } from './llm/types.js';
+
+function isScriptReadableAttachment(attachment: FileAttachment): boolean {
+  if (attachment.isImage) return false;
+  return Boolean(
+    attachment.textContent
+    || attachment.csvData
+    || attachment.csvColumns,
+  );
+}
+
+/**
+ * Collect non-image file attachments from chat history and the current composer.
+ *
+ * Latest attachment wins when the same filename appears multiple times.
+ */
+export function collectActiveFileAttachments(
+  messages: ChatMessage[],
+  pendingAttachments: FileAttachment[] = [],
+): FileAttachment[] {
+  const latestByName = new Map<string, FileAttachment>();
+
+  const remember = (attachment: FileAttachment) => {
+    if (!isScriptReadableAttachment(attachment)) return;
+    if (latestByName.has(attachment.name)) {
+      latestByName.delete(attachment.name);
+    }
+    latestByName.set(attachment.name, attachment);
+  };
+
+  for (const message of messages) {
+    for (const attachment of message.attachments ?? []) {
+      remember(attachment);
+    }
+  }
+
+  for (const attachment of pendingAttachments) {
+    remember(attachment);
+  }
+
+  return Array.from(latestByName.values());
+}

package/src/lib/llm/ClerkChatSync.tsx

@@ -0,0 +1,74 @@
+/* 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 { useEffect } from 'react';
+import { useAuth } from '@clerk/clerk-react';
+import { useViewerStore } from '@/store';
+
+/**
+ * Sync Clerk session state into chat store for authenticated LLM requests.
+ * Keeps chat UX decoupled from auth/billing details.
+ */
+export function ClerkChatSync() {
+  const { isLoaded, isSignedIn, userId, getToken, has } = useAuth();
+  const setChatAuthToken = useViewerStore((s) => s.setChatAuthToken);
+  const switchChatUserContext = useViewerStore((s) => s.switchChatUserContext);
+  const currentChatUserId = useViewerStore((s) => s.chatStorageUserId);
+  const currentChatHasPro = useViewerStore((s) => s.chatHasPro);
+
+  useEffect(() => {
+    if (!isLoaded) return;
+
+    if (!isSignedIn) {
+      switchChatUserContext(null, false, {
+        clearPersistedCurrent: currentChatUserId !== null,
+        restoreMessages: false,
+      });
+      setChatAuthToken(null);
+      return;
+    }
+
+    let cancelled = false;
+
+    const syncAuth = async () => {
+      try {
+        const token = await getToken({ skipCache: true });
+        const proPlan = has?.({ plan: 'pro' }) ?? false;
+        const proFeature = has?.({ feature: 'pro_models' }) ?? false;
+        const nextHasPro = proPlan || proFeature;
+        if (!cancelled) {
+          // Avoid resetting chat usage/messages on routine token refreshes for
+          // the same signed-in user. Only switch context when identity or
+          // entitlement actually changes.
+          if (currentChatUserId !== (userId ?? null) || currentChatHasPro !== nextHasPro) {
+            switchChatUserContext(userId ?? null, nextHasPro, {
+              clearPersistedCurrent: currentChatUserId !== null && currentChatUserId !== userId,
+              restoreMessages: true,
+            });
+          }
+          if (token) {
+            setChatAuthToken(token);
+          }
+        }
+      } catch {
+        if (!cancelled) {
+          // Preserve the current signed-in chat context on transient token
+          // refresh failures. Explicit sign-out is handled above.
+        }
+      }
+    };
+
+    void syncAuth();
+    // Keep short-lived JWTs fresh so chat/usage polling doesn't reuse expired tokens.
+    const timer = window.setInterval(() => {
+      void syncAuth();
+    }, 15_000);
+    return () => {
+      cancelled = true;
+      window.clearInterval(timer);
+    };
+  }, [currentChatHasPro, currentChatUserId, getToken, has, isLoaded, isSignedIn, setChatAuthToken, switchChatUserContext, userId]);
+
+  return null;
+}

package/src/lib/llm/clerk-auth.ts

@@ -0,0 +1,62 @@
+/* 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/. */
+
+/**
+ * Auth helpers for the LLM chat integration.
+ *
+ * Setup:
+ * 1. Install: pnpm add @clerk/clerk-react
+ * 2. Set VITE_CLERK_PUBLISHABLE_KEY in .env
+ * 3. Create plans in dashboard:
+ *    - Free plan (slug: 'free', features: ['llm_chat', 'free_models'])
+ *    - Pro plan (slug: 'pro', $8/month, features: ['llm_chat', 'free_models', 'pro_models'])
+ * 4. Wrap app with <ClerkProvider>
+ *
+ * Usage in components:
+ *
+ * ```tsx
+ * import { useAuth, useUser, Protect } from '@clerk/clerk-react';
+ *
+ * const { has } = useAuth();
+ * const hasPro = has?.({ feature: 'pro_models' }) ?? false;
+ *
+ * const { getToken } = useAuth();
+ * const token = await getToken();
+ * ```
+ */
+
+/**
+ * Subscription tiers and their features.
+ */
+export const SUBSCRIPTION_PLANS = {
+  free: {
+    slug: 'free',
+    name: 'Free',
+    features: ['llm_chat', 'free_models'],
+    description: 'AI chat with free models',
+  },
+  pro: {
+    slug: 'pro',
+    name: 'Pro',
+    features: ['llm_chat', 'free_models', 'pro_models'],
+    description: 'All models with monthly credits ($8/month)',
+  },
+} as const;
+
+/**
+ * Feature flags that map to plan features.
+ */
+export const FEATURES = {
+  LLM_CHAT: 'llm_chat',
+  FREE_MODELS: 'free_models',
+  PRO_MODELS: 'pro_models',
+} as const;
+
+/**
+ * Check if auth is configured (publishable key present).
+ * When not configured, the chat works in anonymous free-tier mode.
+ */
+export function isClerkConfigured(): boolean {
+  return Boolean(import.meta.env.VITE_CLERK_PUBLISHABLE_KEY);
+}

package/src/lib/llm/code-extractor.ts

@@ -0,0 +1,50 @@
+/* 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/. */
+
+/**
+ * Extract executable code blocks from LLM markdown responses.
+ */
+
+import type { CodeBlock } from './types.js';
+
+/**
+ * Parse fenced code blocks from a markdown string.
+ * Supports ```js, ```javascript, ```typescript, ```ts, and bare ``` blocks.
+ */
+export function extractCodeBlocks(markdown: string): CodeBlock[] {
+  const blocks: CodeBlock[] = [];
+  // Match ```lang\n...code...\n```
+  const regex = /```(\w*)\n([\s\S]*?)```/g;
+  let match: RegExpExecArray | null;
+  let index = 0;
+
+  while ((match = regex.exec(markdown)) !== null) {
+    const language = match[1] || 'js';
+    const code = match[2].trim();
+
+    // Only extract JS/TS code blocks (skip html, css, json, etc. unless they look like scripts)
+    const isExecutable = ['js', 'javascript', 'ts', 'typescript', ''].includes(language.toLowerCase());
+    // Also include unlabeled blocks that reference `bim.`
+    const referencesBim = code.includes('bim.');
+
+    if (isExecutable || referencesBim) {
+      blocks.push({ index, language, code });
+      index++;
+    }
+  }
+
+  return blocks;
+}
+
+/**
+ * Inject CSV data into a script as a `const DATA = [...]` declaration.
+ * Prepends the data array before the LLM-generated script body.
+ */
+export function injectCsvData(
+  script: string,
+  data: Record<string, string>[],
+): string {
+  const dataDeclaration = `const DATA = ${JSON.stringify(data)};\n\n`;
+  return dataDeclaration + script;
+}

package/src/lib/llm/context-builder.test.ts

@@ -0,0 +1,18 @@
+/* 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 test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseCSV } from './context-builder.js';
+
+test('parseCSV preserves embedded newlines inside quoted fields', () => {
+  const csv = 'Name,Notes\n"Lobby","Line 1\nLine 2"\n"Office","Single line"';
+
+  const parsed = parseCSV(csv);
+
+  assert.deepEqual(parsed.columns, ['Name', 'Notes']);
+  assert.equal(parsed.rows.length, 2);
+  assert.equal(parsed.rows[0]?.Notes, 'Line 1\nLine 2');
+  assert.equal(parsed.rows[1]?.Notes, 'Single line');
+});