@atlaskit/editor-plugin-autocomplete 2.3.0 → 2.5.0

package/src/analytics/ufo.ts

@@ -0,0 +1,139 @@
+/**
+ * UFO experience tracking helpers for `@atlaskit/editor-plugin-autocomplete`.
+ *
+ * Pattern follows `packages/linking-platform/smart-card/src/state/analytics/ufoExperiences.ts`
+ * (ConcurrentExperience keyed per request/instance) plus a try/catch safety wrap
+ * inspired by `packages/editor/collab-provider/src/analytics/ufo.ts` so a UFO
+ * runtime error can never break the autocomplete feature.
+ *
+ * Experience names must be registered in DataPortal's `task` attribute before
+ * they can power FE Reliability SLOs:
+ * https://hello.atlassian.net/wiki/spaces/AA6/pages/3961393753
+ */
+
+import {
+	ConcurrentExperience,
+	type CustomData,
+	ExperiencePerformanceTypes,
+	ExperienceTypes,
+} from '@atlaskit/ufo';
+
+/**
+ * Experience name strings are surfaced downstream by the UFO pipeline as
+ * `platform.fe.<type>.<platform.component>.<name>` (e.g.
+ * `platform.fe.operation.editor-plugin-autocomplete.slow-lane-fetch`), so
+ * names here should be short, dot-free, and must not repeat the component
+ * name. This matches the convention used by `@atlaskit/emoji`'s
+ * `ufoExperiences` map (e.g. `'emoji-rendered'`).
+ */
+/**
+ * Only experiences with meaningful async work and a real success/failure
+ * outcome belong on UFO (which measures latency and success rate for FE
+ * Reliability SLOs). Per-keystroke suggestion lifecycle counters (viewed /
+ * inserted / dismissed) are tracked via analytics-next instead — they would
+ * otherwise emit zero-duration events on every word boundary.
+ */
+export const EXPERIENCE_NAME = {
+	SLOW_LANE_FETCH: 'slow-lane-fetch',
+	LOAD_VOCABULARY: 'load-vocabulary',
+	LOAD_VECTORS: 'load-vectors',
+} as const;
+
+export type AutocompleteExperienceName =
+	(typeof EXPERIENCE_NAME)[keyof typeof EXPERIENCE_NAME];
+
+const isUfoEnabled = (): boolean => !process?.env?.REACT_SSR;
+
+const operationConfig = {
+	platform: { component: 'editor-plugin-autocomplete' },
+	type: ExperienceTypes.Operation,
+	performanceType: ExperiencePerformanceTypes.Custom,
+	performanceConfig: {
+		histogram: {
+			[ExperiencePerformanceTypes.Custom]: {
+				duration: '50_100_250_500_1000_2000_4000',
+			},
+		},
+	},
+};
+
+const experiences: Record<AutocompleteExperienceName, ConcurrentExperience> = {
+	[EXPERIENCE_NAME.SLOW_LANE_FETCH]: new ConcurrentExperience(
+		EXPERIENCE_NAME.SLOW_LANE_FETCH,
+		operationConfig,
+	),
+	[EXPERIENCE_NAME.LOAD_VOCABULARY]: new ConcurrentExperience(
+		EXPERIENCE_NAME.LOAD_VOCABULARY,
+		operationConfig,
+	),
+	[EXPERIENCE_NAME.LOAD_VECTORS]: new ConcurrentExperience(
+		EXPERIENCE_NAME.LOAD_VECTORS,
+		operationConfig,
+	),
+};
+
+export const startExp = (
+	name: AutocompleteExperienceName,
+	id: string,
+	metadata?: CustomData,
+): void => {
+	if (!isUfoEnabled()) {
+		return;
+	}
+	try {
+		const instance = experiences[name].getInstance(id);
+		instance.start();
+		if (metadata) {
+			instance.addMetadata(metadata);
+		}
+	} catch {
+		// UFO errors must never break the plugin
+	}
+};
+
+export const succeedExp = (
+	name: AutocompleteExperienceName,
+	id: string,
+	metadata?: CustomData,
+): void => {
+	if (!isUfoEnabled()) {
+		return;
+	}
+	try {
+		experiences[name].getInstance(id).success({ metadata });
+	} catch {
+		// UFO errors must never break the plugin
+	}
+};
+
+export const failExp = (
+	name: AutocompleteExperienceName,
+	id: string,
+	metadata?: CustomData,
+): void => {
+	if (!isUfoEnabled()) {
+		return;
+	}
+	try {
+		experiences[name].getInstance(id).failure({ metadata });
+	} catch {
+		// UFO errors must never break the plugin
+	}
+};
+
+export const abortExp = (
+	name: AutocompleteExperienceName,
+	id: string,
+	reason?: string,
+): void => {
+	if (!isUfoEnabled()) {
+		return;
+	}
+	try {
+		experiences[name]
+			.getInstance(id)
+			.abort(reason ? { metadata: { reason } } : undefined);
+	} catch {
+		// UFO errors must never break the plugin
+	}
+};

package/src/entry-points/autocompletePlugin.tsx

@@ -0,0 +1,2 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+export { autocompletePlugin } from '../autocompletePlugin';

package/src/entry-points/autocompletePluginType.ts

@@ -0,0 +1,2 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+export type { AutocompletePlugin } from '../autocompletePluginType';

package/src/entry-points/src-pm-plugins-autocomplete-plugin.ts

@@ -0,0 +1,7 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+export { autocompletePluginKey, createAutocompletePlugin } from '../pm-plugins/autocomplete-plugin';
+export type {
+	AutocompleteContext,
+	AutocompletePluginOptions,
+	AutocompletePluginState,
+} from '../pm-plugins/autocomplete-plugin';

package/src/entry-points/src-pm-plugins-slow-lane-client.ts

@@ -0,0 +1,13 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+export {
+	createSlowLaneClient,
+	getStoredContextVector,
+	getStoredLmLogits,
+	isWordBoundary,
+	setDefaultSlowLaneClient,
+} from '../pm-plugins/slow-lane-client';
+export type {
+	SlowLaneClientConfig,
+	TypeaheadEncodingsRequest,
+	TypeaheadEncodingsResponse,
+} from '../pm-plugins/slow-lane-client';

package/src/entry-points/src-pm-plugins-text-predictor.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @atlaskit/editor/no-re-export */
+export {
+	getLastPredictionDebug,
+	getPredictorStatus,
+	incrementSessionFreq,
+	ingestDocumentPage,
+	initL3Vocabulary,
+	initVectors,
+	initVocabulary,
+	loadDefaultVocabulary,
+	loadVectorsAsync,
+	predict,
+} from '../pm-plugins/text-predictor';
+export type { TenantVocabulary, WeightedTerm } from '../pm-plugins/text-predictor';

package/src/pm-plugins/autocomplete-plugin/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@atlaskit/editor-plugin-autocomplete/src/pm-plugins/autocomplete-plugin",
-  "main": "../../../dist/cjs/pm-plugins/autocomplete-plugin.js",
-  "module": "../../../dist/esm/pm-plugins/autocomplete-plugin.js",
-  "module:es2019": "../../../dist/es2019/pm-plugins/autocomplete-plugin.js",
+  "main": "../../../dist/cjs/entry-points/src-pm-plugins-autocomplete-plugin.js",
+  "module": "../../../dist/esm/entry-points/src-pm-plugins-autocomplete-plugin.js",
+  "module:es2019": "../../../dist/es2019/entry-points/src-pm-plugins-autocomplete-plugin.js",
   "sideEffects": false,
-  "types": "../../../dist/types/pm-plugins/autocomplete-plugin.d.ts",
+  "types": "../../../dist/types/entry-points/src-pm-plugins-autocomplete-plugin.d.ts",
   "typesVersions": {
     ">=4.5 <5.9": {
       "*": [
-        "../../../dist/types-ts4.5/pm-plugins/autocomplete-plugin.d.ts"
+        "../../../dist/types-ts4.5/entry-points/src-pm-plugins-autocomplete-plugin.d.ts"
       ]
     }
   }

package/src/pm-plugins/autocomplete-plugin.ts

@@ -1,4 +1,5 @@
 import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
+import { logException } from '@atlaskit/editor-common/monitoring';
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
 import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
 import { keydownHandler } from '@atlaskit/editor-prosemirror/keymap';
@@ -14,6 +15,7 @@ import type { EditorView } from '@atlaskit/editor-prosemirror/view';
 import type { AutocompletePlugin } from '../autocompletePluginType';
 
 import { createGhostTextDecorationSet } from './ghost-text-decoration';
+import { createLocalSlowLaneClient, type LocalSlowLaneClient } from './local-slow-lane-client';
 import { createSlowLaneClient, setDefaultSlowLaneClient, isWordBoundary } from './slow-lane-client';
 import {
 	predict,
@@ -23,12 +25,15 @@ import {
 	ingestDocumentPage,
 } from './text-predictor';
 
-const SLOW_LANE_ENDPOINT = '/gateway/api/v1/autocomplete/typeahead-encodings';
-
 export const autocompletePluginKey: PluginKey = new PluginKey('autocomplete');
 
 const DEBOUNCE_MS = 150;
 
+const hasDestroy = (
+	client: ReturnType<typeof createSlowLaneClient> | LocalSlowLaneClient,
+): client is LocalSlowLaneClient =>
+	'destroy' in client && typeof client.destroy === 'function';
+
 export interface AutocompletePluginState {
 	/** The decoration set containing the ghost text widget */
 	decorationSet: DecorationSet;
@@ -97,14 +102,18 @@ const setAutocompleteMeta = (
 let lastShownGhostText = '';
 
 const showGhostText = (view: EditorView, text: string, position: number): void => {
-	const { state, dispatch } = view;
-	const decorationSet = createGhostTextDecorationSet(state, position, text);
-	const tr = setAutocompleteMeta(state.tr, {
-		ghostText: text,
-		ghostPosition: position,
-		decorationSet,
-	});
-	dispatch(tr);
+	try {
+		const { state, dispatch } = view;
+		const decorationSet = createGhostTextDecorationSet(state, position, text);
+		const tr = setAutocompleteMeta(state.tr, {
+			ghostText: text,
+			ghostPosition: position,
+			decorationSet,
+		});
+		dispatch(tr);
+	} catch (error) {
+		logException(error as Error, { location: 'editor-plugin-autocomplete/showGhostText' });
+	}
 };
 
 /**
@@ -117,12 +126,17 @@ const clearGhostText = (state: EditorState, dispatch?: (tr: Transaction) => void
 	}
 
 	if (dispatch) {
-		const tr = setAutocompleteMeta(state.tr, {
-			ghostText: '',
-			ghostPosition: -1,
-			decorationSet: DecorationSet.empty,
-		});
-		dispatch(tr);
+		try {
+			const tr = setAutocompleteMeta(state.tr, {
+				ghostText: '',
+				ghostPosition: -1,
+				decorationSet: DecorationSet.empty,
+			});
+			dispatch(tr);
+		} catch (error) {
+			logException(error as Error, { location: 'editor-plugin-autocomplete/clearGhostText' });
+			return false;
+		}
 	}
 	return true;
 };
@@ -137,14 +151,19 @@ const acceptGhostText = (state: EditorState, dispatch?: (tr: Transaction) => voi
 	}
 
 	if (dispatch) {
-		const { ghostText, ghostPosition } = pluginState;
-		let tr = state.tr.insertText(ghostText, ghostPosition);
-		tr = setAutocompleteMeta(tr, {
-			ghostText: '',
-			ghostPosition: -1,
-			decorationSet: DecorationSet.empty,
-		});
-		dispatch(tr);
+		try {
+			const { ghostText, ghostPosition } = pluginState;
+			let tr = state.tr.insertText(ghostText, ghostPosition);
+			tr = setAutocompleteMeta(tr, {
+				ghostText: '',
+				ghostPosition: -1,
+				decorationSet: DecorationSet.empty,
+			});
+			dispatch(tr);
+		} catch (error) {
+			logException(error as Error, { location: 'editor-plugin-autocomplete/acceptGhostText' });
+			return false;
+		}
 	}
 	return true;
 };
@@ -178,6 +197,11 @@ export interface AutocompletePluginOptions {
 	 * Use this to serve vectors from a CDN or media service in production.
 	 */
 	getVectorsBinaryUrl?: () => Promise<string>;
+	/**
+	 * When true, uses on-device inference via WebGPU (MLC WebLLM) instead of
+	 * the network-based slow-lane backend. Defaults to false (network client).
+	 */
+	useLocalModel?: boolean;
 }
 
 /**
@@ -235,6 +259,15 @@ export const createAutocompletePlugin = (
 	let lastSuggestionTypedLength = 0;
 	let lastSuggestionLength = 0;
 
+	const fireSuggestionDismissedAnalytics = (reason: 'escape' | 'blur'): void => {
+		api?.analytics?.actions.fireAnalyticsEvent({
+			action: ACTION.SUGGESTION_DISMISSED,
+			actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+			eventType: EVENT_TYPE.TRACK,
+			attributes: { reason },
+		});
+	};
+
 	const fireSuggestionInsertedAnalytics = (ghostText: string): void => {
 		const typedLength = lastSuggestionTypedLength;
 		const suggestionLength = lastSuggestionLength || typedLength + ghostText.length;
@@ -252,10 +285,14 @@ export const createAutocompletePlugin = (
 		});
 	};
 
-	const slowLaneClient = createSlowLaneClient({
-		baseUrl: '',
-		endpoint: SLOW_LANE_ENDPOINT,
-	});
+	const slowLaneClient = options?.useLocalModel
+		? createLocalSlowLaneClient({
+				debounceMs: 300,
+			})
+		: createSlowLaneClient({
+				baseUrl: '',
+				debounceMs: 300,
+			});
 	setDefaultSlowLaneClient(slowLaneClient);
 
 	/**
@@ -269,45 +306,51 @@ export const createAutocompletePlugin = (
 		}
 
 		debounceTimer = setTimeout(() => {
-			const { state } = view;
-			const { selection } = state;
+			try {
+				const { state } = view;
+				const { selection } = state;
 
-			// Only predict for cursor selections (not range selections)
-			if (!selection.empty) {
-				return;
-			}
+				// Only predict for cursor selections (not range selections)
+				if (!selection.empty) {
+					return;
+				}
 
-			const textBefore = getTextBeforeCursor(state);
+				const textBefore = getTextBeforeCursor(state);
 
-			// Suppress re-showing the same suggestion the user just dismissed.
-			// Once the text context changes (user types or deletes), this clears automatically.
-			if (textBefore === dismissedContext) {
-				return;
-			}
-			dismissedContext = null;
+				// Suppress re-showing the same suggestion the user just dismissed.
+				// Once the text context changes (user types or deletes), this clears automatically.
+				if (textBefore === dismissedContext) {
+					return;
+				}
+				dismissedContext = null;
 
-			// Don't predict if there's not enough context
-			if (textBefore.trim().length < 3) {
-				return;
-			}
+				// Don't predict if there's not enough context
+				if (textBefore.trim().length < 3) {
+					return;
+				}
 
-			// Tier 1 prediction is synchronous -- no async needed
-			const prediction = predict(textBefore);
-
-			if (prediction && prediction.length > 0) {
-				const typedLength = getTypedLengthForPrediction(textBefore);
-				lastSuggestionTypedLength = typedLength;
-				lastSuggestionLength = typedLength + prediction.length;
-
-				showGhostText(view, prediction, selection.from);
-				if (prediction !== lastShownGhostText) {
-					lastShownGhostText = prediction;
-					api?.analytics?.actions.fireAnalyticsEvent({
-						action: ACTION.SUGGESTION_VIEWED,
-						actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
-						eventType: EVENT_TYPE.TRACK,
-					});
+				// Tier 1 prediction is synchronous -- no async needed
+				const prediction = predict(textBefore);
+
+				if (prediction && prediction.length > 0) {
+					const typedLength = getTypedLengthForPrediction(textBefore);
+					lastSuggestionTypedLength = typedLength;
+					lastSuggestionLength = typedLength + prediction.length;
+
+					showGhostText(view, prediction, selection.from);
+					if (prediction !== lastShownGhostText) {
+						lastShownGhostText = prediction;
+						api?.analytics?.actions.fireAnalyticsEvent({
+							action: ACTION.SUGGESTION_VIEWED,
+							actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+							eventType: EVENT_TYPE.TRACK,
+						});
+					}
 				}
+			} catch (error) {
+				logException(error as Error, {
+					location: 'editor-plugin-autocomplete/schedulePrediction',
+				});
 			}
 		}, DEBOUNCE_MS);
 	};
@@ -424,6 +467,7 @@ export const createAutocompletePlugin = (
 					const didClear = clearGhostText(state, dispatch);
 					if (didClear) {
 						dismissedContext = getTextBeforeCursor(state);
+						fireSuggestionDismissedAnalytics('escape');
 					}
 					return didClear;
 				},
@@ -436,12 +480,23 @@ export const createAutocompletePlugin = (
 						| undefined;
 					if (pluginState?.ghostText) {
 						clearGhostText(view.state, view.dispatch);
+						fireSuggestionDismissedAnalytics('blur');
 					}
 					return false;
 				},
 				focus: () => {
-					loadDefaultVocabulary();
-					loadVectorsAsync({ getBinaryUrl: options?.getVectorsBinaryUrl }).catch(() => {});
+					try {
+						loadDefaultVocabulary();
+					} catch (error) {
+						logException(error as Error, {
+							location: 'editor-plugin-autocomplete/loadDefaultVocabulary',
+						});
+					}
+					loadVectorsAsync({ getBinaryUrl: options?.getVectorsBinaryUrl }).catch((error) => {
+						logException(error as Error, {
+							location: 'editor-plugin-autocomplete/loadVectorsAsync',
+						});
+					});
 					if (!hasIngestedPage) {
 						hasIngestedPage = true;
 						if (options?.getContext) {
@@ -461,7 +516,11 @@ export const createAutocompletePlugin = (
 									}
 									context.siblingCommentsContents?.forEach(ingestDocumentPage);
 								})
-								.catch(() => {});
+								.catch((error) => {
+									logException(error as Error, {
+										location: 'editor-plugin-autocomplete/getContext',
+									});
+								});
 						}
 					}
 					return false;
@@ -503,6 +562,9 @@ export const createAutocompletePlugin = (
 				if (debounceTimer) {
 					clearTimeout(debounceTimer);
 				}
+				if (hasDestroy(slowLaneClient)) {
+					slowLaneClient.destroy();
+				}
 				setDefaultSlowLaneClient(null);
 			},
 		}),