@atlaskit/editor-plugin-autocomplete 9.0.0 → 9.1.0

package/dist/types/pm-plugins/debug-mode.d.ts

@@ -28,6 +28,16 @@ declare global {
             isEnabled: () => boolean;
             /** Whether verbose logging (candidate tables + extra detail) is on. */
             isVerbose: () => boolean;
+            /**
+             * Snapshot of the L1 session boosts — the vocabulary words this session
+             * has seen and how often — or one family of them:
+             * `__atlCtcDebug__.session('poll')`.
+             *
+             * Installed by the predictor rather than declared with the rest of the
+             * API, and typed as `unknown` so the return shape can live with the module
+             * that owns it instead of creating a cycle back to this one.
+             */
+            session?: (prefix?: string) => unknown;
         };
     }
 }
@@ -60,3 +70,12 @@ export declare const ctcSection: (label: string, body: string) => void;
 export declare const ctcTag: (tag: string, body: string, tagStyle?: string) => void;
 export declare const isAutocompleteDebugEnabled: () => boolean;
 export declare const isAutocompleteDebugVerbose: () => boolean;
+/**
+ * Hang the L1 session-boost snapshot off the console API.
+ *
+ * Unlike the log helpers this is available whether or not debug is enabled:
+ * inspecting state on demand is not logging, and asking someone to turn on
+ * logging and retype to find out what the session already holds defeats the
+ * point of being able to ask.
+ */
+export declare const registerCtcSessionInspector: (inspect: (prefix?: string) => unknown) => void;

package/dist/types/pm-plugins/text-predictor.d.ts

@@ -12,7 +12,10 @@
  * Falls back to cold mode (freq-only) when vectors not yet loaded.
  *
  * Session personalization (L1): words the user types are incrementally boosted
- * via incrementSessionFreq(), called on word boundaries from the plugin.
+ * via incrementSessionFreq(), called on word boundaries from the plugin, and
+ * words in ingested context text via ingestDocumentPage(). What the session has
+ * boosted is visible at any time from the console: `__atlCtcDebug__.session()`,
+ * or `__atlCtcDebug__.session('poll')` for one family — see inspectSessionBoosts.
  */
 import type { TermType } from './scoring-pipeline';
 export interface WeightedTerm {
@@ -111,6 +114,38 @@ export declare const incrementSessionFreq: (word: string) => void;
  * calling context does not yet have a page value available.
  */
 export declare const ingestDocumentPage: (pageContent: string | undefined) => void;
+interface SessionWordSnapshot {
+    /** Times this session has seen it: words typed plus words in ingested text. */
+    sessionFreq: number;
+    /** No corpus frequency behind it, so L1 is the whole of its standing. */
+    sessionOnly: boolean;
+    surface: string;
+    /** Corpus frequency shipped with the vocabulary, for scale against the boost. */
+    tenantFreq: number;
+}
+export interface SessionSnapshot {
+    /** How many words hold a boost, whether or not they are listed below. */
+    boosted: number;
+    /** Ceiling on `words`; beyond it the weakest boosts are left out of the listing. */
+    limit: number;
+    /** The prefix asked about, when one was passed. */
+    prefix?: string;
+    /** Strongest boost first, then alphabetically. */
+    words: SessionWordSnapshot[];
+}
+/**
+ * Read the session's L1 boosts, optionally narrowed to a prefix.
+ *
+ * Installed as `__atlCtcDebug__.session()`, with `__atlCtcDebug__.session('poll')`
+ * to ask about one family. Returned rather than logged, so the console renders it
+ * as an inspectable object and a caller can assert on it.
+ *
+ * Only words the vocabulary already holds can carry a boost, because both writers
+ * go through `incrementSessionFreq` and it only finds existing nodes. An ingested
+ * word absent from the vocabulary is therefore missing from here and always will
+ * be.
+ */
+export declare const inspectSessionBoosts: (prefix?: string) => SessionSnapshot;
 /**
  * Result of a prediction: the ghost tail to insert plus an immutable record of
  * the evidence that authorized the UI commitment.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-autocomplete",
-	"version": "9.0.0",
+	"version": "9.1.0",
 	"description": "Client-side text autocomplete plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -27,7 +27,7 @@
 		"wink-nlp": "^2.4.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^119.4.0",
+		"@atlaskit/editor-common": "^119.9.0",
 		"@atlaskit/editor-plugin-analytics": "^15.0.0",
 		"react": "^18.2.0 || ^19.2.0"
 	},

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

@@ -669,7 +669,67 @@ export const createAutocompletePlugin = (
 	// Set when the plugin is torn down so in-flight getContext() resolutions don't
 	// mutate the global text-predictor state after destruction.
 	let destroyed = false;
-	const ingestedContextTexts = new Set<string>();
+	// L1 ingestion cannot run before the vocabulary has loaded: `incrementSessionFreq`
+	// only touches trie nodes that already exist, so an empty trie silently rejects
+	// every word. Text that arrives first — which a page usually does, since the
+	// chat resolves it on focus in the same tick as the load starts — is held here
+	// and applied once the load has settled.
+	const pendingSessionContextTexts = new Set<string>();
+	const sessionIngestedContextTexts = new Set<string>();
+	let isVocabularyReady = false;
+	let vocabularyLoadPromise: Promise<void> | undefined;
+
+	const addBoundedContextText = (texts: Set<string>, text: string): void => {
+		texts.add(text);
+		// Evict oldest entries (Set preserves insertion order) to bound memory.
+		while (texts.size > MAX_INGESTED_CONTEXT_TEXTS) {
+			const oldest = texts.values().next().value;
+			if (oldest === undefined) {
+				break;
+			}
+			texts.delete(oldest);
+		}
+	};
+
+	const flushPendingSessionContext = (): void => {
+		if (!isVocabularyReady || destroyed) {
+			return;
+		}
+		for (const text of pendingSessionContextTexts) {
+			if (!sessionIngestedContextTexts.has(text)) {
+				ingestDocumentPage(text);
+				addBoundedContextText(sessionIngestedContextTexts, text);
+			}
+			pendingSessionContextTexts.delete(text);
+		}
+	};
+
+	const ensureVocabularyReady = (): Promise<void> => {
+		if (isVocabularyReady) {
+			flushPendingSessionContext();
+			return Promise.resolve();
+		}
+		vocabularyLoadPromise ??= loadDefaultVocabulary({
+			isLocalLLM: options?.useLocalModel ?? false,
+			surface,
+		})
+			.then(() => {
+				if (destroyed) {
+					return;
+				}
+				isVocabularyReady = true;
+				flushPendingSessionContext();
+			})
+			.catch((error) => {
+				// Do not consume the pending text on failure. A later focus retries the
+				// load and can still apply the original context exactly once.
+				vocabularyLoadPromise = undefined;
+				logException(error as Error, {
+					location: 'editor-plugin-autocomplete/loadDefaultVocabulary',
+				});
+			});
+		return vocabularyLoadPromise;
+	};
 
 	const logContextResolved = (source: string, context?: AutocompleteContext): void => {
 		if (!isAutocompleteDebugEnabled()) {
@@ -698,20 +758,11 @@ export const createAutocompletePlugin = (
 		resolvedContext = { ...resolvedContext, ...definedContext };
 
 		const ingestContextText = (text?: string): void => {
-			if (!text || ingestedContextTexts.has(text)) {
+			if (!text || sessionIngestedContextTexts.has(text)) {
 				return;
 			}
 
-			ingestedContextTexts.add(text);
-			// Evict oldest entries (Set preserves insertion order) to bound memory.
-			while (ingestedContextTexts.size > MAX_INGESTED_CONTEXT_TEXTS) {
-				const oldest = ingestedContextTexts.values().next().value;
-				if (oldest === undefined) {
-					break;
-				}
-				ingestedContextTexts.delete(oldest);
-			}
-			ingestDocumentPage(text);
+			addBoundedContextText(pendingSessionContextTexts, text);
 		};
 
 		ingestContextText(context.fullPageContent);
@@ -719,6 +770,7 @@ export const createAutocompletePlugin = (
 		for (const siblingCommentContent of context.siblingCommentsContents ?? []) {
 			ingestContextText(siblingCommentContent);
 		}
+		flushPendingSessionContext();
 
 		// Context arrived after word boundaries may already have fired. Re-send
 		// slow-lane context immediately so the next inference includes the thread.
@@ -1198,14 +1250,7 @@ export const createAutocompletePlugin = (
 						return false;
 					}
 
-					loadDefaultVocabulary({
-						isLocalLLM: options?.useLocalModel ?? false,
-						surface,
-					}).catch((error) => {
-						logException(error as Error, {
-							location: 'editor-plugin-autocomplete/loadDefaultVocabulary',
-						});
-					});
+					void ensureVocabularyReady();
 					loadVectorsAsync({
 						isLocalLLM: options?.useLocalModel ?? false,
 						surface,
@@ -1313,7 +1358,8 @@ export const createAutocompletePlugin = (
 					if (hasDestroy(slowLaneClient)) {
 						slowLaneClient.destroy();
 					}
-					ingestedContextTexts.clear();
+					pendingSessionContextTexts.clear();
+					sessionIngestedContextTexts.clear();
 				},
 			};
 		},

package/src/pm-plugins/debug-mode.ts

@@ -29,6 +29,16 @@ declare global {
 			isEnabled: () => boolean;
 			/** Whether verbose logging (candidate tables + extra detail) is on. */
 			isVerbose: () => boolean;
+			/**
+			 * Snapshot of the L1 session boosts — the vocabulary words this session
+			 * has seen and how often — or one family of them:
+			 * `__atlCtcDebug__.session('poll')`.
+			 *
+			 * Installed by the predictor rather than declared with the rest of the
+			 * API, and typed as `unknown` so the return shape can live with the module
+			 * that owns it instead of creating a cycle back to this one.
+			 */
+			session?: (prefix?: string) => unknown;
 		};
 	}
 }
@@ -120,7 +130,7 @@ const printLegend = (verbose: boolean): void => {
 	);
 	// eslint-disable-next-line no-console
 	console.log(
-		'%cInspect%c   __atlCtcDebug__.enable("verbose") · .disable()',
+		'%cInspect%c   __atlCtcDebug__.enable("verbose") · .disable() · .session() (L1 boosts, narrow to a family with .session("poll"))',
 		CTC_STYLES.section,
 		CTC_STYLES.body,
 	);
@@ -163,5 +173,20 @@ export const isAutocompleteDebugEnabled = (): boolean => getDebugApi()?.isEnable
 
 export const isAutocompleteDebugVerbose = (): boolean => getDebugApi()?.isVerbose() ?? false;
 
+/**
+ * Hang the L1 session-boost snapshot off the console API.
+ *
+ * Unlike the log helpers this is available whether or not debug is enabled:
+ * inspecting state on demand is not logging, and asking someone to turn on
+ * logging and retype to find out what the session already holds defeats the
+ * point of being able to ask.
+ */
+export const registerCtcSessionInspector = (inspect: (prefix?: string) => unknown): void => {
+	const api = getDebugApi();
+	if (api) {
+		api.session = inspect;
+	}
+};
+
 // Eagerly install so the console API is available on load, regardless of call order.
 getDebugApi();

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

@@ -12,7 +12,10 @@
  * Falls back to cold mode (freq-only) when vectors not yet loaded.
  *
  * Session personalization (L1): words the user types are incrementally boosted
- * via incrementSessionFreq(), called on word boundaries from the plugin.
+ * via incrementSessionFreq(), called on word boundaries from the plugin, and
+ * words in ingested context text via ingestDocumentPage(). What the session has
+ * boosted is visible at any time from the console: `__atlCtcDebug__.session()`,
+ * or `__atlCtcDebug__.session('poll')` for one family — see inspectSessionBoosts.
  */
 
 import { EXPERIENCE_NAME, failExp, startExp, succeedExp } from '../analytics/ufo';
@@ -35,6 +38,7 @@ import {
 	ctcTag,
 	isAutocompleteDebugEnabled,
 	isAutocompleteDebugVerbose,
+	registerCtcSessionInspector,
 } from './debug-mode';
 import {
 	loadGrammarDataAsync,
@@ -388,6 +392,44 @@ class WeightedWordTrie {
 		node.sessionFreq += 1;
 		return true;
 	}
+
+	/**
+	 * Every word carrying a session boost, optionally limited to one prefix's
+	 * subtree. Unlike `getCandidates` a word equal to the prefix is included,
+	 * since the question here is what the session holds rather than what could
+	 * still be typed.
+	 *
+	 * Walks the trie instead of reading an index, so nothing has to be kept in
+	 * step on the write path for the sake of being able to ask.
+	 */
+	collectSessionBoosted(prefix: string = ''): Candidate[] {
+		let node = this.root;
+		for (const char of prefix.toLowerCase()) {
+			const next = node.children.get(char);
+			if (!next) {
+				return [];
+			}
+			node = next;
+		}
+
+		const boosted: Candidate[] = [];
+		const stack: TrieNode[] = [node];
+
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current) {
+				continue;
+			}
+			if (current.word !== null && current.sessionFreq > 0) {
+				boosted.push({ word: current.word, node: current });
+			}
+			for (const child of current.children.values()) {
+				stack.push(child);
+			}
+		}
+
+		return boosted;
+	}
 }
 
 // L1/L2 Trie (Session + Atlassian Domain)
@@ -823,7 +865,11 @@ export const ingestDocumentPage = (pageContent: string | undefined): void => {
 	}
 
 	if (isAutocompleteDebugEnabled() && validBoostedWords.size > 0) {
-		ctcTag('init', `L1 session primed ${validBoostedWords.size} words from page`, CTC_STYLES.brand);
+		ctcTag(
+			'init',
+			`L1 session primed ${validBoostedWords.size} words from page · __atlCtcDebug__.session() to inspect`,
+			CTC_STYLES.brand,
+		);
 		if (isAutocompleteDebugVerbose()) {
 			// eslint-disable-next-line no-console
 			console.dir(Array.from(validBoostedWords).sort());
@@ -831,6 +877,74 @@ export const ingestDocumentPage = (pageContent: string | undefined): void => {
 	}
 };
 
+/**
+ * How many boosted words `inspectSessionBoosts` lists.
+ *
+ * A page ingest can boost thousands, and a list that long is not read. The
+ * strongest boosts are the ones that change an ordering, and `boosted` still
+ * reports the full size, so the cap loses nothing but volume.
+ */
+const MAX_LISTED_SESSION_WORDS = 50;
+
+interface SessionWordSnapshot {
+	/** Times this session has seen it: words typed plus words in ingested text. */
+	sessionFreq: number;
+	/** No corpus frequency behind it, so L1 is the whole of its standing. */
+	sessionOnly: boolean;
+	surface: string;
+	/** Corpus frequency shipped with the vocabulary, for scale against the boost. */
+	tenantFreq: number;
+}
+
+export interface SessionSnapshot {
+	/** How many words hold a boost, whether or not they are listed below. */
+	boosted: number;
+	/** Ceiling on `words`; beyond it the weakest boosts are left out of the listing. */
+	limit: number;
+	/** The prefix asked about, when one was passed. */
+	prefix?: string;
+	/** Strongest boost first, then alphabetically. */
+	words: SessionWordSnapshot[];
+}
+
+/**
+ * Read the session's L1 boosts, optionally narrowed to a prefix.
+ *
+ * Installed as `__atlCtcDebug__.session()`, with `__atlCtcDebug__.session('poll')`
+ * to ask about one family. Returned rather than logged, so the console renders it
+ * as an inspectable object and a caller can assert on it.
+ *
+ * Only words the vocabulary already holds can carry a boost, because both writers
+ * go through `incrementSessionFreq` and it only finds existing nodes. An ingested
+ * word absent from the vocabulary is therefore missing from here and always will
+ * be.
+ */
+export const inspectSessionBoosts = (prefix?: string): SessionSnapshot => {
+	const boosted = wordTrie.collectSessionBoosted(prefix ?? '');
+	return {
+		boosted: boosted.length,
+		limit: MAX_LISTED_SESSION_WORDS,
+		...(prefix === undefined ? {} : { prefix }),
+		words: boosted
+			.sort(
+				(a, b) =>
+					b.node.sessionFreq - a.node.sessionFreq ||
+					a.word.localeCompare(b.word, 'en', { numeric: true, sensitivity: 'base' }),
+			)
+			.slice(0, MAX_LISTED_SESSION_WORDS)
+			.map(({ node, word }) => ({
+				sessionFreq: node.sessionFreq,
+				sessionOnly: node.tenantFreq === 0,
+				surface: word,
+				tenantFreq: node.tenantFreq,
+			})),
+	};
+};
+
+// At module scope so the console answers before the first keystroke, which is
+// when someone reaching for it usually asks.
+registerCtcSessionInspector(inspectSessionBoosts);
+
 /**
  * Result of a prediction: the ghost tail to insert plus an immutable record of
  * the evidence that authorized the UI commitment.