@atlaskit/editor-plugin-autocomplete 3.5.0 → 3.6.0

package/dist/es2019/pm-plugins/local-slow-lane-client.js

@@ -43,6 +43,19 @@ import { isWordBoundary } from './slow-lane-client';
 
 // Same return type as createSlowLaneClient for drop-in compatibility
 
+/**
+ * Why the local engine failed to load/start.
+ *
+ * The first three are user-machine limitations (WebGPU missing, no compatible
+ * GPU adapter, GPU lacks the `shader-f16` feature the model needs);
+ * `insufficient_memory` is hit when weights don't fit in VRAM. The rest cover
+ * delivery/runtime failures unrelated to hardware.
+ */
+
+/** Snapshot of the machine's WebGPU support, used to explain hardware limits. */
+
+// Minimal WebGPU shape: lib.dom types aren't guaranteed in this build target.
+
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 const DEFAULT_DEBOUNCE_MS = 300;
@@ -470,6 +483,8 @@ export const createLocalSlowLaneClient = (config = {}) => {
     debounceMs = DEFAULT_DEBOUNCE_MS,
     onUpdate,
     onStatus,
+    onLoadError,
+    onLoadSuccess,
     modelId = LOCAL_MLC_CAUSAL_MODEL_ID,
     customModelConfig
   } = config;
@@ -516,16 +531,129 @@ export const createLocalSlowLaneClient = (config = {}) => {
     }
     onStatus === null || onStatus === void 0 ? void 0 : onStatus(message);
   };
+  const bytesToMB = bytes => typeof bytes === 'number' ? Math.round(bytes / (1024 * 1024)) : undefined;
+
+  /**
+   * Inspect the machine's WebGPU support so a load failure can be attributed
+   * to a concrete hardware/browser limitation rather than a generic error.
+   */
+  const probeWebGpuCapabilities = async () => {
+    const gpu = navigator.gpu;
+    if (!gpu) {
+      return {
+        available: false
+      };
+    }
+    try {
+      var _adapter$limits, _adapter$limits2;
+      const adapter = await gpu.requestAdapter();
+      if (!adapter) {
+        return {
+          available: true,
+          adapterAvailable: false
+        };
+      }
+      let vendor;
+      let architecture;
+      try {
+        var _adapter$info, _adapter$requestAdapt;
+        const info = (_adapter$info = adapter.info) !== null && _adapter$info !== void 0 ? _adapter$info : await ((_adapter$requestAdapt = adapter.requestAdapterInfo) === null || _adapter$requestAdapt === void 0 ? void 0 : _adapter$requestAdapt.call(adapter));
+        vendor = (info === null || info === void 0 ? void 0 : info.vendor) || undefined;
+        architecture = (info === null || info === void 0 ? void 0 : info.architecture) || undefined;
+      } catch {
+        // adapter info is best-effort
+      }
+      return {
+        available: true,
+        adapterAvailable: true,
+        shaderF16Supported: adapter.features.has('shader-f16'),
+        maxBufferSizeMB: bytesToMB((_adapter$limits = adapter.limits) === null || _adapter$limits === void 0 ? void 0 : _adapter$limits.maxBufferSize),
+        maxStorageBufferBindingSizeMB: bytesToMB((_adapter$limits2 = adapter.limits) === null || _adapter$limits2 === void 0 ? void 0 : _adapter$limits2.maxStorageBufferBindingSize),
+        vendor,
+        architecture
+      };
+    } catch {
+      return {
+        available: true,
+        adapterAvailable: false
+      };
+    }
+  };
+
+  /** Map an MLC/WebLLM engine-creation error message to a coarse reason. */
+  const classifyEngineError = message => {
+    const lower = message.toLowerCase();
+    if (lower.includes('loading chunk') || lower.includes('dynamically imported module') || lower.includes('dynamic import')) {
+      return 'module_load_failed';
+    }
+    if (lower.includes('out of memory') || /\boom\b/u.test(lower) || lower.includes('allocation') || lower.includes('exceeds') || lower.includes('buffer size') || lower.includes('not enough memory')) {
+      return 'insufficient_memory';
+    }
+    // Pre-flight already returns missing_shader_f16 when the feature is absent,
+    // so only match the exact feature token here — not bare 'shader' (compile
+    // errors) or bare 'f16' (present in model ids like q0f16-MLC).
+    if (lower.includes('shader-f16') || lower.includes('shader_f16')) {
+      return 'missing_shader_f16';
+    }
+    if (lower.includes('fetch') || lower.includes('network') || lower.includes('download') || lower.includes('http') || lower.includes('cache')) {
+      return 'model_download_failed';
+    }
+    return 'init_failed';
+  };
+
+  // Canonical, controlled failure descriptions. We never emit the raw engine
+  // error into analytics — it can embed customer-context URLs/paths (HOT-120175)
+  // — so the analytics `message` is always one of these fixed strings.
+  const LOAD_FAILURE_MESSAGE = {
+    webgpu_unavailable: 'WebGPU is not available in this browser',
+    webgpu_no_adapter: 'No compatible WebGPU adapter found',
+    missing_shader_f16: 'GPU does not support the shader-f16 feature',
+    insufficient_memory: 'Insufficient GPU memory to load the model',
+    model_download_failed: 'Failed to download model assets',
+    module_load_failed: 'Failed to load the web-llm runtime module',
+    init_failed: 'Model engine failed to initialise'
+  };
+  const handleLoadFailure = (reason, capabilities, debugDetail) => {
+    ready = false;
+    const message = LOAD_FAILURE_MESSAGE[reason];
+    if (isAutocompleteDebugEnabled()) {
+      // eslint-disable-next-line no-console
+      console.log(`[LocalSlowLane] Engine initialisation failed (${reason}): ${debugDetail !== null && debugDetail !== void 0 ? debugDetail : message}`);
+    }
+    onStatus === null || onStatus === void 0 ? void 0 : onStatus(`Engine initialisation failed: ${message}`);
+    onLoadError === null || onLoadError === void 0 ? void 0 : onLoadError({
+      reason,
+      message,
+      modelId,
+      embeddingModelId: LOCAL_MLC_EMBEDDING_MODEL_ID,
+      capabilities
+    });
+    engineInitPromise = null;
+    initFailed = true;
+  };
   const initEngine = async () => {
+    const capabilities = await probeWebGpuCapabilities();
+
+    // ── Pre-flight: machine limitations short-circuit before the expensive load ──
+    if (!capabilities.available) {
+      handleLoadFailure('webgpu_unavailable', capabilities);
+      return;
+    }
+    if (capabilities.adapterAvailable === false) {
+      handleLoadFailure('webgpu_no_adapter', capabilities);
+      return;
+    }
+    if (capabilities.shaderF16Supported === false) {
+      handleLoadFailure('missing_shader_f16', capabilities);
+      return;
+    }
+    const startTime = performance.now();
     try {
       if (isAutocompleteDebugEnabled()) {
         // eslint-disable-next-line no-console
         console.log(`%c[LocalSlowLane] %c🚀 Initialising MLC engine with models: ${modelId} (LM) + ${LOCAL_MLC_EMBEDDING_MODEL_ID} (embedder)`, 'color: #9c27b0; font-weight: bold;', 'color: inherit;');
       }
       onStatus === null || onStatus === void 0 ? void 0 : onStatus(`Initialising models: ${modelId} + ${LOCAL_MLC_EMBEDDING_MODEL_ID}…`);
-      if (!('gpu' in navigator)) {
-        throw new Error('WebGPU not supported');
-      }
 
       // Fetch the web-llm runtime and the BE-parity lookup tables in parallel;
       // both are dynamically imported so they stay out of the main editor chunk.
@@ -568,6 +696,7 @@ export const createLocalSlowLaneClient = (config = {}) => {
       }
       engine = newEngine;
       ready = true;
+      const loadDurationMs = Math.round(performance.now() - startTime);
       if (isAutocompleteDebugEnabled()) {
         // eslint-disable-next-line no-console
         console.log('%c[LocalSlowLane] %c✅ Both models loaded and ready', 'color: #9c27b0; font-weight: bold;', 'color: #4caf50;');
@@ -579,16 +708,15 @@ export const createLocalSlowLaneClient = (config = {}) => {
         console.log('%c[LocalSlowLane] %c🔢 Embedder     →', 'color: #9c27b0; font-weight: bold;', 'color: #009688; font-weight: bold;', LOCAL_MLC_EMBEDDING_MODEL_ID);
       }
       onStatus === null || onStatus === void 0 ? void 0 : onStatus('Model loaded and ready.');
+      onLoadSuccess === null || onLoadSuccess === void 0 ? void 0 : onLoadSuccess({
+        modelId,
+        embeddingModelId: LOCAL_MLC_EMBEDDING_MODEL_ID,
+        loadDurationMs,
+        capabilities
+      });
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      ready = false;
-      if (isAutocompleteDebugEnabled()) {
-        // eslint-disable-next-line no-console
-        console.log(`[LocalSlowLane] Engine initialisation failed: ${errorMsg}`);
-      }
-      onStatus === null || onStatus === void 0 ? void 0 : onStatus(`Engine initialisation failed: ${errorMsg}`);
-      engineInitPromise = null;
-      initFailed = true;
+      handleLoadFailure(classifyEngineError(errorMsg), capabilities, errorMsg);
     }
   };
   const ensureEngineInitialized = () => {

package/dist/esm/pm-plugins/autocomplete-plugin.js

@@ -240,12 +240,49 @@ export var createAutocompletePlugin = function createAutocompletePlugin(options,
       }
     });
   };
-  var fireSuggestionInsertedAnalytics = function fireSuggestionInsertedAnalytics(ghostText) {
+  var fireLocalModelLoadedAnalytics = function fireLocalModelLoadedAnalytics(info) {
     var _api$analytics2;
+    api === null || api === void 0 || (_api$analytics2 = api.analytics) === null || _api$analytics2 === void 0 || _api$analytics2.actions.fireAnalyticsEvent({
+      action: ACTION.LOCAL_MODEL_LOADED,
+      actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+      eventType: EVENT_TYPE.TRACK,
+      attributes: {
+        modelId: info.modelId,
+        embeddingModelId: info.embeddingModelId,
+        loadDurationMs: info.loadDurationMs,
+        gpuVendor: info.capabilities.vendor,
+        gpuArchitecture: info.capabilities.architecture
+      }
+    });
+  };
+  var fireLocalModelLoadFailedAnalytics = function fireLocalModelLoadFailedAnalytics(error) {
+    var _api$analytics3;
+    var capabilities = error.capabilities;
+    api === null || api === void 0 || (_api$analytics3 = api.analytics) === null || _api$analytics3 === void 0 || _api$analytics3.actions.fireAnalyticsEvent({
+      action: ACTION.LOCAL_MODEL_LOAD_FAILED,
+      actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+      eventType: EVENT_TYPE.TRACK,
+      attributes: {
+        reason: error.reason,
+        message: error.message,
+        modelId: error.modelId,
+        embeddingModelId: error.embeddingModelId,
+        webgpuAvailable: capabilities.available,
+        adapterAvailable: capabilities.adapterAvailable,
+        shaderF16Supported: capabilities.shaderF16Supported,
+        maxBufferSizeMB: capabilities.maxBufferSizeMB,
+        maxStorageBufferBindingSizeMB: capabilities.maxStorageBufferBindingSizeMB,
+        gpuVendor: capabilities.vendor,
+        gpuArchitecture: capabilities.architecture
+      }
+    });
+  };
+  var fireSuggestionInsertedAnalytics = function fireSuggestionInsertedAnalytics(ghostText) {
+    var _api$analytics4;
     var typedLength = lastSuggestionTypedLength;
     var suggestionLength = lastSuggestionLength || typedLength + ghostText.length;
     var kssDelta = suggestionLength - typedLength;
-    api === null || api === void 0 || (_api$analytics2 = api.analytics) === null || _api$analytics2 === void 0 || _api$analytics2.actions.fireAnalyticsEvent({
+    api === null || api === void 0 || (_api$analytics4 = api.analytics) === null || _api$analytics4 === void 0 || _api$analytics4.actions.fireAnalyticsEvent({
       action: ACTION.SUGGESTION_INSERTED,
       actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
       eventType: EVENT_TYPE.TRACK,
@@ -258,7 +295,9 @@ export var createAutocompletePlugin = function createAutocompletePlugin(options,
     });
   };
   var slowLaneClient = options !== null && options !== void 0 && options.useLocalModel ? createLocalSlowLaneClient({
-    debounceMs: LOCAL_SLOW_LANE_DEBOUNCE_MS
+    debounceMs: LOCAL_SLOW_LANE_DEBOUNCE_MS,
+    onLoadSuccess: fireLocalModelLoadedAnalytics,
+    onLoadError: fireLocalModelLoadFailedAnalytics
   }) : createSlowLaneClient({
     baseUrl: '',
     debounceMs: NETWORK_SLOW_LANE_DEBOUNCE_MS
@@ -412,9 +451,9 @@ export var createAutocompletePlugin = function createAutocompletePlugin(options,
           lastSuggestionLength = typedLength + prediction.length;
           showGhostText(view, prediction, selection.from);
           if (prediction !== lastShownGhostText) {
-            var _api$analytics3;
+            var _api$analytics5;
             lastShownGhostText = prediction;
-            api === null || api === void 0 || (_api$analytics3 = api.analytics) === null || _api$analytics3 === void 0 || _api$analytics3.actions.fireAnalyticsEvent({
+            api === null || api === void 0 || (_api$analytics5 = api.analytics) === null || _api$analytics5 === void 0 || _api$analytics5.actions.fireAnalyticsEvent({
               action: ACTION.SUGGESTION_VIEWED,
               actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
               eventType: EVENT_TYPE.TRACK,