@atlaskit/editor-plugin-autocomplete 2.0.0 → 2.2.0

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

@@ -1,6 +1,7 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
 import { keydownHandler } from '@atlaskit/editor-prosemirror/keymap';
 import { PluginKey } from '@atlaskit/editor-prosemirror/state';
@@ -61,6 +62,7 @@ var setAutocompleteMeta = function setAutocompleteMeta(tr, meta) {
 /**
  * Apply a ghost text suggestion to the editor state.
  */
+var lastShownGhostText = '';
 var showGhostText = function showGhostText(view, text, position) {
   var state = view.state,
     dispatch = view.dispatch;
@@ -139,7 +141,7 @@ var buildSlowLaneText = function buildSlowLaneText(docText, context) {
   lines.push("reply ".concat(nextReplyNumber, ": ").concat(docText));
   return lines.join('\n');
 };
-export var createAutocompletePlugin = function createAutocompletePlugin(options) {
+export var createAutocompletePlugin = function createAutocompletePlugin(options, api) {
   var debounceTimer = null;
   var hasIngestedPage = false;
   var resolvedContext;
@@ -197,6 +199,15 @@ export var createAutocompletePlugin = function createAutocompletePlugin(options)
       var prediction = predict(textBefore);
       if (prediction && prediction.length > 0) {
         showGhostText(view, prediction, selection.from);
+        if (prediction !== lastShownGhostText) {
+          var _api$analytics;
+          lastShownGhostText = prediction;
+          api === null || api === void 0 || (_api$analytics = api.analytics) === null || _api$analytics === void 0 || _api$analytics.actions.fireAnalyticsEvent({
+            action: ACTION.SUGGESTION_VIEWED,
+            actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+            eventType: EVENT_TYPE.TRACK
+          });
+        }
       }
     }, DEBOUNCE_MS);
   };
@@ -268,12 +279,30 @@ export var createAutocompletePlugin = function createAutocompletePlugin(options)
       handleKeyDown: keydownHandler({
         Tab: function Tab(state, dispatch) {
           var accepted = acceptGhostText(state, dispatch);
-          if (accepted) justAccepted = true;
+          if (accepted) {
+            var _api$analytics2;
+            justAccepted = true;
+            lastShownGhostText = '';
+            api === null || api === void 0 || (_api$analytics2 = api.analytics) === null || _api$analytics2 === void 0 || _api$analytics2.actions.fireAnalyticsEvent({
+              action: ACTION.SUGGESTION_INSERTED,
+              actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+              eventType: EVENT_TYPE.TRACK
+            });
+          }
           return accepted;
         },
         ArrowRight: function ArrowRight(state, dispatch) {
           var accepted = acceptGhostText(state, dispatch);
-          if (accepted) justAccepted = true;
+          if (accepted) {
+            var _api$analytics3;
+            justAccepted = true;
+            lastShownGhostText = '';
+            api === null || api === void 0 || (_api$analytics3 = api.analytics) === null || _api$analytics3 === void 0 || _api$analytics3.actions.fireAnalyticsEvent({
+              action: ACTION.SUGGESTION_INSERTED,
+              actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+              eventType: EVENT_TYPE.TRACK
+            });
+          }
           return accepted;
         },
         Escape: function Escape(state, dispatch) {

package/dist/esm/pm-plugins/scoring-pipeline.js

@@ -22,10 +22,15 @@ import grammarTransitionsData from './data/grammar_transitions_10k.json';
 var ALPHA = 0.5;
 var BETA = 0.5;
 var NEUTRAL_SCORE = 0.5;
-var STAGE1_WEIGHT = 0.6;
-var STAGE2_WEIGHT = 0.4;
-var MIN_STAGE1_SCORE = 0.35;
+export var STAGE1_WEIGHT = 0.35;
+export var STAGE2_WEIGHT = 0.65;
+export var MIN_STAGE1_SCORE = 0.35;
 var L1_SESSION_CAP = 1.2;
+// Minimum prefix-payload max LM probability before Stage 2 activates.
+// Below this threshold the LM signal is too weak to suppress Stage 1 — finalScore
+// falls back to stage1Score directly. Prevents weak prefixes (e.g. "ins" → "instances"
+// at 0.00024) from triggering re-ranking.
+var LM_GATE_THRESHOLD = 0.0005;
 
 // ─── Grammar Data (loaded once on import) ───────────────────
 
@@ -189,6 +194,7 @@ function getLmScore(word, lmLogits) {
 // ─── Public API ─────────────────────────────────────────────
 
 export function rankCandidates(candidates, contextVector, getWordVector, lmLogits, maxTenantFreq, previousWord) {
+  var _grammarMeta$dropped;
   // Stage 1
   var stage1Results = candidates.map(function (candidate) {
     var _scoreStage = scoreStage1(candidate, contextVector, getWordVector, maxTenantFreq),
@@ -202,33 +208,48 @@ export function rankCandidates(candidates, contextVector, getWordVector, lmLogit
       stage1Score: stage1Score
     };
   });
-  var stage1Survivors = stage1Results.filter(function (entry) {
-    return entry.stage1Score >= MIN_STAGE1_SCORE;
-  });
+  var stage1Survivors = [];
+  var stage1Rejected = [];
+  var _iterator3 = _createForOfIteratorHelper(stage1Results),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var entry = _step3.value;
+      if (entry.stage1Score >= MIN_STAGE1_SCORE) {
+        stage1Survivors.push(entry);
+      } else {
+        stage1Rejected.push(entry.candidate.word);
+      }
+    }
 
-  // Grammar Filter
+    // Grammar Filter
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
   var _applyGrammarFilter = applyGrammarFilter(stage1Survivors, previousWord),
     filtered = _applyGrammarFilter.filtered,
     grammarMeta = _applyGrammarFilter.grammarMeta;
 
   // Stage 2 + final assembly
   var lmMax = 0;
-  if (lmLogits && Object.keys(lmLogits).length > 0) {
+  if (lmLogits) {
     var values = Object.values(lmLogits);
-    lmMax = Math.max.apply(Math, values);
+    if (values.length > 0) lmMax = Math.max.apply(Math, values);
   }
   var scored = filtered.map(function (entry) {
     var lmScore = 0;
     var finalScore = entry.stage1Score;
-    if (lmLogits && Object.keys(lmLogits).length > 0) {
+    if (lmLogits && lmMax >= LM_GATE_THRESHOLD) {
       var rawLm = getLmScore(entry.candidate.word, lmLogits);
       if (rawLm !== 0) {
-        // The word was in the top_k! Score it normally.
         var logitDiff = Math.log(rawLm) - Math.log(lmMax);
         lmScore = Math.exp(logitDiff);
-      } else {
-        lmScore = 0.05;
       }
+      // Words absent from the prefix-filtered payload get lmScore = 0,
+      // not 0.05, so they don't outrank genuine LM predictions.
+
       finalScore = STAGE1_WEIGHT * entry.stage1Score + STAGE2_WEIGHT * lmScore;
     }
     return {
@@ -240,13 +261,17 @@ export function rankCandidates(candidates, contextVector, getWordVector, lmLogit
     };
   });
   scored.sort(function (a, b) {
-    if (b.finalScore !== a.finalScore) {
-      return b.finalScore - a.finalScore;
-    }
+    if (b.finalScore !== a.finalScore) return b.finalScore - a.finalScore;
     return a.word.length - b.word.length;
   });
   return {
     candidates: scored,
-    grammarMeta: grammarMeta
+    grammarMeta: grammarMeta,
+    pipelineDebug: {
+      initial: candidates.length,
+      stage1Rejected: stage1Rejected,
+      grammarRejected: (_grammarMeta$dropped = grammarMeta === null || grammarMeta === void 0 ? void 0 : grammarMeta.dropped) !== null && _grammarMeta$dropped !== void 0 ? _grammarMeta$dropped : [],
+      final: scored.length
+    }
   };
 }

package/dist/esm/pm-plugins/text-predictor.js

@@ -29,7 +29,7 @@ import l3VocabularyData from './data/l3_vocabulary.json';
 import vocabularyData from './data/vocabulary_10k.json';
 import wordIndexData from './data/word_index_10k.json';
 // import { rankCandidates, isGrammarAllowed } from './scoring-pipeline';
-import { rankCandidates } from './scoring-pipeline';
+import { rankCandidates, STAGE1_WEIGHT, STAGE2_WEIGHT, MIN_STAGE1_SCORE } from './scoring-pipeline';
 import { getStoredContextVector, getStoredLmLogits } from './slow-lane-client';
 
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -570,11 +570,21 @@ export var predict = function predict(textBefore) {
       sessionFreq: node.sessionFreq
     };
   });
+
+  // Filter the LM payload to only words matching the current prefix so that
+  // lmMax in rankCandidates reflects prefix-relevant signal, not the global distribution.
+  var prefix = currentWord.toLowerCase();
+  var prefixLmLogits = lmLogits ? Object.fromEntries(Object.entries(lmLogits).filter(function (_ref4) {
+    var _ref5 = _slicedToArray(_ref4, 1),
+      word = _ref5[0];
+    return word.startsWith(prefix);
+  })) : null;
   var _rankCandidates = rankCandidates(scoringCandidates, contextVector, function (w) {
       return getWordVector(w);
-    }, lmLogits, wordTrie.maxTenantFreq, previousWord),
+    }, prefixLmLogits, wordTrie.maxTenantFreq, previousWord),
     ranked = _rankCandidates.candidates,
-    grammarMeta = _rankCandidates.grammarMeta;
+    grammarMeta = _rankCandidates.grammarMeta,
+    pipelineDebug = _rankCandidates.pipelineDebug;
   var best = ranked[0];
   var suggestion = best && best.finalScore >= MIN_SCORE_THRESHOLD ? best.word.slice(currentWord.length) : null;
   if (debugMode) {
@@ -621,7 +631,7 @@ export var predict = function predict(textBefore) {
     console.log('%cSlow Lane:', 'color: #888; font-style: italic;', vectorStatus, '|', logitsStatus);
 
     // 4. Scoring formula active this prediction
-    var formulaLabel = lmLogits && Object.keys(lmLogits).length > 0 ? 'Stage1(×0.6) + LM(×0.4)' : 'Stage1 only (no LM logits)';
+    var formulaLabel = lmLogits && Object.keys(lmLogits).length > 0 ? "Stage1(\xD7".concat(STAGE1_WEIGHT, ") + LM(\xD7").concat(STAGE2_WEIGHT, ")") : 'Stage1 only (no LM logits)';
     // eslint-disable-next-line no-console
     console.log('%cFormula:', 'color: #888; font-style: italic;', formulaLabel);
 
@@ -635,17 +645,21 @@ export var predict = function predict(textBefore) {
       }
     }
 
-    // 6. Candidate table
+    // 6. Pipeline funnel
+    // eslint-disable-next-line no-console
+    console.log("%c[Pipeline Funnel] %c\uD83D\uDCE5 In: ".concat(pipelineDebug.initial, " | \u274C Stage 1 (< ").concat(MIN_STAGE1_SCORE, "): -").concat(pipelineDebug.stage1Rejected.length, " | \u274C Grammar: -").concat(pipelineDebug.grammarRejected.length, " | \u2705 Final: ").concat(pipelineDebug.final), 'color: #9c27b0; font-weight: bold;', 'color: inherit;');
+
+    // 7. Candidate table
     if (ranked.length > 0) {
       var lmCoverage = ranked.slice(0, 10).filter(function (r) {
-        return r.lmScore > 0.05;
+        return r.lmScore > 0;
       }).length;
       // eslint-disable-next-line no-console
       console.log("%cLM coverage: ".concat(lmCoverage, "/").concat(Math.min(ranked.length, 10), " candidates had real logit scores"), 'color: #888; font-style: italic;');
       var tableData = ranked.slice(0, 10).map(function (r) {
         var rawLogit = 'Not in Payload';
-        if (lmLogits) {
-          var val = lmLogits[r.word.toLowerCase()];
+        if (prefixLmLogits) {
+          var val = prefixLmLogits[r.word.toLowerCase()];
           if (val !== undefined) {
             rawLogit = Number(val.toFixed(5));
           }
@@ -691,7 +705,7 @@ export var predict = function predict(textBefore) {
 // ─── Data Loading ────────────────────────────────────────────────────────────
 
 export var loadVectorsAsync = /*#__PURE__*/function () {
-  var _ref4 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(options) {
+  var _ref6 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(options) {
     var url, res, buffer, float32, wordIndex, nWords, dim;
     return _regeneratorRuntime.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
@@ -777,7 +791,7 @@ export var loadVectorsAsync = /*#__PURE__*/function () {
     }, _callee, null, [[6, 12], [17, 37]]);
   }));
   return function loadVectorsAsync(_x) {
-    return _ref4.apply(this, arguments);
+    return _ref6.apply(this, arguments);
   };
 }();
 export var initVectors = function initVectors(store) {
@@ -786,10 +800,10 @@ export var initVectors = function initVectors(store) {
 export var loadDefaultVocabulary = function loadDefaultVocabulary() {
   // 1. Load the Atlassian Domain (L2)
   var data = vocabularyData;
-  var terms = Object.entries(data.words).map(function (_ref5) {
-    var _ref6 = _slicedToArray(_ref5, 2),
-      word = _ref6[0],
-      stats = _ref6[1];
+  var terms = Object.entries(data.words).map(function (_ref7) {
+    var _ref8 = _slicedToArray(_ref7, 2),
+      word = _ref8[0],
+      stats = _ref8[1];
     return {
       word: word,
       freq: stats.freq,

package/dist/types/autocompletePluginType.d.ts

@@ -1,6 +1,8 @@
-import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { NextEditorPlugin, OptionalPlugin } from '@atlaskit/editor-common/types';
+import type { AnalyticsPlugin } from '@atlaskit/editor-plugin-analytics';
 import type { AutocompletePluginOptions, AutocompletePluginState } from './pm-plugins/autocomplete-plugin';
 export type AutocompletePlugin = NextEditorPlugin<'autocomplete', {
     pluginConfiguration?: AutocompletePluginOptions | undefined;
     sharedState: AutocompletePluginState | undefined;
+    dependencies: [OptionalPlugin<AnalyticsPlugin>];
 }>;

package/dist/types/pm-plugins/autocomplete-plugin.d.ts

@@ -1,6 +1,8 @@
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
 import { PluginKey } from '@atlaskit/editor-prosemirror/state';
 import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+import type { AutocompletePlugin } from '../autocompletePluginType';
 export declare const autocompletePluginKey: PluginKey<any>;
 export interface AutocompletePluginState {
     /** The decoration set containing the ghost text widget */
@@ -39,4 +41,4 @@ export interface AutocompletePluginOptions {
      */
     getVectorsBinaryUrl?: () => Promise<string>;
 }
-export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions) => SafePlugin<AutocompletePluginState>;
+export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions, api?: ExtractInjectionAPI<AutocompletePlugin>) => SafePlugin<AutocompletePluginState>;

package/dist/types/pm-plugins/scoring-pipeline.d.ts

@@ -26,8 +26,18 @@ export interface GrammarFilterMeta {
     prevTags: string[];
     prevWord: string;
 }
+export declare const STAGE1_WEIGHT = 0.35;
+export declare const STAGE2_WEIGHT = 0.65;
+export declare const MIN_STAGE1_SCORE = 0.35;
+export interface PipelineDebug {
+    final: number;
+    grammarRejected: string[];
+    initial: number;
+    stage1Rejected: string[];
+}
 export interface RankCandidatesResult {
     candidates: ScoredCandidate[];
     grammarMeta: GrammarFilterMeta | null;
+    pipelineDebug: PipelineDebug;
 }
 export declare function rankCandidates(candidates: ScoringCandidate[], contextVector: Float32Array | null, getWordVector: (word: string) => Float32Array | null, lmLogits: Record<string, number> | null, maxTenantFreq: number, previousWord: string): RankCandidatesResult;

package/dist/types-ts4.5/autocompletePluginType.d.ts

@@ -1,6 +1,10 @@
-import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { NextEditorPlugin, OptionalPlugin } from '@atlaskit/editor-common/types';
+import type { AnalyticsPlugin } from '@atlaskit/editor-plugin-analytics';
 import type { AutocompletePluginOptions, AutocompletePluginState } from './pm-plugins/autocomplete-plugin';
 export type AutocompletePlugin = NextEditorPlugin<'autocomplete', {
     pluginConfiguration?: AutocompletePluginOptions | undefined;
     sharedState: AutocompletePluginState | undefined;
+    dependencies: [
+        OptionalPlugin<AnalyticsPlugin>
+    ];
 }>;

package/dist/types-ts4.5/pm-plugins/autocomplete-plugin.d.ts

@@ -1,6 +1,8 @@
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
 import { PluginKey } from '@atlaskit/editor-prosemirror/state';
 import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+import type { AutocompletePlugin } from '../autocompletePluginType';
 export declare const autocompletePluginKey: PluginKey<any>;
 export interface AutocompletePluginState {
     /** The decoration set containing the ghost text widget */
@@ -39,4 +41,4 @@ export interface AutocompletePluginOptions {
      */
     getVectorsBinaryUrl?: () => Promise<string>;
 }
-export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions) => SafePlugin<AutocompletePluginState>;
+export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions, api?: ExtractInjectionAPI<AutocompletePlugin>) => SafePlugin<AutocompletePluginState>;

package/dist/types-ts4.5/pm-plugins/scoring-pipeline.d.ts

@@ -26,8 +26,18 @@ export interface GrammarFilterMeta {
     prevTags: string[];
     prevWord: string;
 }
+export declare const STAGE1_WEIGHT = 0.35;
+export declare const STAGE2_WEIGHT = 0.65;
+export declare const MIN_STAGE1_SCORE = 0.35;
+export interface PipelineDebug {
+    final: number;
+    grammarRejected: string[];
+    initial: number;
+    stage1Rejected: string[];
+}
 export interface RankCandidatesResult {
     candidates: ScoredCandidate[];
     grammarMeta: GrammarFilterMeta | null;
+    pipelineDebug: PipelineDebug;
 }
 export declare function rankCandidates(candidates: ScoringCandidate[], contextVector: Float32Array | null, getWordVector: (word: string) => Float32Array | null, lmLogits: Record<string, number> | null, maxTenantFreq: number, previousWord: string): RankCandidatesResult;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-autocomplete",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "Client-side text autocomplete plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -33,7 +33,8 @@
 		"wink-nlp": "^2.4.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^114.0.0",
+		"@atlaskit/editor-common": "^114.5.0",
+		"@atlaskit/editor-plugin-analytics": "^10.0.0",
 		"react": "^18.2.0"
 	},
 	"techstack": {

package/src/autocompletePlugin.tsx

@@ -2,7 +2,7 @@ import type { AutocompletePlugin } from './autocompletePluginType';
 import { autocompletePluginKey, createAutocompletePlugin } from './pm-plugins/autocomplete-plugin';
 import type { AutocompletePluginState } from './pm-plugins/autocomplete-plugin';
 
-export const autocompletePlugin: AutocompletePlugin = ({ config: options }) => {
+export const autocompletePlugin: AutocompletePlugin = ({ config: options, api }) => {
 	return {
 		name: 'autocomplete',
 		getSharedState(editorState): AutocompletePluginState | undefined {
@@ -16,7 +16,7 @@ export const autocompletePlugin: AutocompletePlugin = ({ config: options }) => {
 			return [
 				{
 					name: 'autocomplete',
-					plugin: () => createAutocompletePlugin(options),
+					plugin: () => createAutocompletePlugin(options, api),
 				},
 			];
 		},

package/src/autocompletePluginType.ts

@@ -1,4 +1,5 @@
-import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { NextEditorPlugin, OptionalPlugin } from '@atlaskit/editor-common/types';
+import type { AnalyticsPlugin } from '@atlaskit/editor-plugin-analytics';
 
 import type {
 	AutocompletePluginOptions,
@@ -10,5 +11,6 @@ export type AutocompletePlugin = NextEditorPlugin<
 	{
 		pluginConfiguration?: AutocompletePluginOptions | undefined;
 		sharedState: AutocompletePluginState | undefined;
+		dependencies: [OptionalPlugin<AnalyticsPlugin>];
 	}
 >;

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

@@ -1,4 +1,6 @@
+import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
 import { keydownHandler } from '@atlaskit/editor-prosemirror/keymap';
 import { PluginKey } from '@atlaskit/editor-prosemirror/state';
 import type {
@@ -9,6 +11,8 @@ import type {
 import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
 import type { EditorView } from '@atlaskit/editor-prosemirror/view';
 
+import type { AutocompletePlugin } from '../autocompletePluginType';
+
 import { createGhostTextDecorationSet } from './ghost-text-decoration';
 import { createSlowLaneClient, setDefaultSlowLaneClient, isWordBoundary } from './slow-lane-client';
 import {
@@ -90,6 +94,8 @@ const setAutocompleteMeta = (
 /**
  * Apply a ghost text suggestion to the editor state.
  */
+let lastShownGhostText = '';
+
 const showGhostText = (view: EditorView, text: string, position: number): void => {
 	const { state, dispatch } = view;
 	const decorationSet = createGhostTextDecorationSet(state, position, text);
@@ -196,7 +202,7 @@ const buildSlowLaneText = (docText: string, context?: AutocompleteContext): stri
 	return lines.join('\n');
 };
 
-export const createAutocompletePlugin = (options?: AutocompletePluginOptions) => {
+export const createAutocompletePlugin = (options?: AutocompletePluginOptions, api?: ExtractInjectionAPI<AutocompletePlugin>) => {
 	let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 	let hasIngestedPage = false;
 	let resolvedContext: AutocompleteContext | undefined;
@@ -258,6 +264,14 @@ export const createAutocompletePlugin = (options?: AutocompletePluginOptions) =>
 
 			if (prediction && prediction.length > 0) {
 				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,
+					});
+				}
 			}
 		}, DEBOUNCE_MS);
 	};
@@ -346,12 +360,28 @@ export const createAutocompletePlugin = (options?: AutocompletePluginOptions) =>
 			handleKeyDown: keydownHandler({
 				Tab: (state: EditorState, dispatch?: (tr: Transaction) => void) => {
 					const accepted = acceptGhostText(state, dispatch);
-					if (accepted) justAccepted = true;
+					if (accepted) {
+						justAccepted = true;
+						lastShownGhostText = '';
+						api?.analytics?.actions.fireAnalyticsEvent({
+							action: ACTION.SUGGESTION_INSERTED,
+							actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+							eventType: EVENT_TYPE.TRACK,
+						});
+					}
 					return accepted;
 				},
 				ArrowRight: (state: EditorState, dispatch?: (tr: Transaction) => void) => {
 					const accepted = acceptGhostText(state, dispatch);
-					if (accepted) justAccepted = true;
+					if (accepted) {
+						justAccepted = true;
+						lastShownGhostText = '';
+						api?.analytics?.actions.fireAnalyticsEvent({
+							action: ACTION.SUGGESTION_INSERTED,
+							actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+							eventType: EVENT_TYPE.TRACK,
+						});
+					}
 					return accepted;
 				},
 				Escape: (state: EditorState, dispatch?: (tr: Transaction) => void) => {

package/src/pm-plugins/scoring-pipeline.ts

@@ -49,10 +49,15 @@ interface GrammarTransitions {
 const ALPHA = 0.5;
 const BETA = 0.5;
 const NEUTRAL_SCORE = 0.5;
-const STAGE1_WEIGHT = 0.6;
-const STAGE2_WEIGHT = 0.4;
-const MIN_STAGE1_SCORE = 0.35;
+export const STAGE1_WEIGHT = 0.35;
+export const STAGE2_WEIGHT = 0.65;
+export const MIN_STAGE1_SCORE = 0.35;
 const L1_SESSION_CAP = 1.2;
+// Minimum prefix-payload max LM probability before Stage 2 activates.
+// Below this threshold the LM signal is too weak to suppress Stage 1 — finalScore
+// falls back to stage1Score directly. Prevents weak prefixes (e.g. "ins" → "instances"
+// at 0.00024) from triggering re-ranking.
+const LM_GATE_THRESHOLD = 0.0005;
 
 // ─── Grammar Data (loaded once on import) ───────────────────
 
@@ -217,9 +222,17 @@ function getLmScore(word: string, lmLogits: Record<string, number> | null): numb
 
 // ─── Public API ─────────────────────────────────────────────
 
+export interface PipelineDebug {
+	final: number;
+	grammarRejected: string[];
+	initial: number;
+	stage1Rejected: string[];
+}
+
 export interface RankCandidatesResult {
 	candidates: ScoredCandidate[];
 	grammarMeta: GrammarFilterMeta | null;
+	pipelineDebug: PipelineDebug;
 }
 
 export function rankCandidates(
@@ -240,33 +253,39 @@ export function rankCandidates(
 		);
 		return { candidate, semanticScore, freqScore, stage1Score };
 	});
-
-	const stage1Survivors = stage1Results.filter((entry) => entry.stage1Score >= MIN_STAGE1_SCORE);
+	const stage1Survivors: typeof stage1Results = [];
+	const stage1Rejected: string[] = [];
+	for (const entry of stage1Results) {
+		if (entry.stage1Score >= MIN_STAGE1_SCORE) {
+			stage1Survivors.push(entry);
+		} else {
+			stage1Rejected.push(entry.candidate.word);
+		}
+	}
 
 	// Grammar Filter
 	const { filtered, grammarMeta } = applyGrammarFilter(stage1Survivors, previousWord);
 
 	// Stage 2 + final assembly
 	let lmMax = 0;
-	if (lmLogits && Object.keys(lmLogits).length > 0) {
+	if (lmLogits) {
 		const values = Object.values(lmLogits);
-		lmMax = Math.max(...values);
+		if (values.length > 0) lmMax = Math.max(...values);
 	}
 
 	const scored: ScoredCandidate[] = filtered.map((entry) => {
 		let lmScore = 0;
 		let finalScore = entry.stage1Score;
 
-		if (lmLogits && Object.keys(lmLogits).length > 0) {
+		if (lmLogits && lmMax >= LM_GATE_THRESHOLD) {
 			const rawLm = getLmScore(entry.candidate.word, lmLogits);
 
 			if (rawLm !== 0) {
-				// The word was in the top_k! Score it normally.
 				const logitDiff = Math.log(rawLm) - Math.log(lmMax);
 				lmScore = Math.exp(logitDiff);
-			} else {
-				lmScore = 0.05;
 			}
+			// Words absent from the prefix-filtered payload get lmScore = 0,
+			// not 0.05, so they don't outrank genuine LM predictions.
 
 			finalScore = STAGE1_WEIGHT * entry.stage1Score + STAGE2_WEIGHT * lmScore;
 		}
@@ -281,11 +300,18 @@ export function rankCandidates(
 	});
 
 	scored.sort((a, b) => {
-		if (b.finalScore !== a.finalScore) {
-			return b.finalScore - a.finalScore;
-		}
+		if (b.finalScore !== a.finalScore) return b.finalScore - a.finalScore;
 		return a.word.length - b.word.length;
 	});
 
-	return { candidates: scored, grammarMeta };
+	return {
+		candidates: scored,
+		grammarMeta,
+		pipelineDebug: {
+			initial: candidates.length,
+			stage1Rejected,
+			grammarRejected: grammarMeta?.dropped ?? [],
+			final: scored.length,
+		},
+	};
 }