@atlaskit/editor-plugin-autocomplete 0.1.0 → 0.3.0

package/dist/types/autocompletePluginType.d.ts

@@ -1,3 +1,6 @@
-export type AutocompletePlugin = () => {
-    name: 'autocomplete';
-};
+import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { AutocompletePluginOptions, AutocompletePluginState } from './pm-plugins/autocomplete-plugin';
+export type AutocompletePlugin = NextEditorPlugin<'autocomplete', {
+    pluginConfiguration?: AutocompletePluginOptions | undefined;
+    sharedState: AutocompletePluginState | undefined;
+}>;

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

@@ -0,0 +1,36 @@
+import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import { PluginKey } from '@atlaskit/editor-prosemirror/state';
+import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+export declare const autocompletePluginKey: PluginKey<any>;
+export interface AutocompletePluginState {
+    /** The decoration set containing the ghost text widget */
+    decorationSet: DecorationSet;
+    /** The document position where the ghost text should appear */
+    ghostPosition: number;
+    /** The predicted ghost text to display */
+    ghostText: string;
+}
+/**
+ * Context provided to the autocomplete plugin on first editor focus.
+ * Text fields are selectively ingested to boost word-frequency scoring for
+ * predictions, giving words already present in the document/thread an L1
+ * priority boost.
+ */
+export interface AutocompleteContext {
+    /** Full page content as a string (e.g. markdown). */
+    fullPageContent?: string;
+    /** The currently selected text on the page, if any. */
+    pageSelectionContent?: string;
+    /** Content of the parent comment when the editor is in reply or edit mode. */
+    parentCommentContent?: string;
+    /** Contents of sibling comments when the editor is in reply or edit mode. */
+    siblingCommentsContents?: string[];
+}
+export interface AutocompletePluginOptions {
+    /**
+     * Async function called once on first editor focus to retrieve context for
+     * word-frequency boosting. Called lazily so the preset can remain synchronous.
+     */
+    getContext?: () => Promise<AutocompleteContext | undefined>;
+}
+export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions) => SafePlugin<any>;

package/dist/types/pm-plugins/ghost-text-decoration.d.ts

@@ -0,0 +1,7 @@
+import type { EditorState } from '@atlaskit/editor-prosemirror/state';
+import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+/**
+ * Creates a DecorationSet containing a ghost text widget at the given position.
+ * The ghost text is rendered as a styled <span> that appears after the cursor.
+ */
+export declare const createGhostTextDecorationSet: (state: EditorState, position: number, text: string) => DecorationSet;

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

@@ -0,0 +1,33 @@
+/**
+ * Scoring Pipeline: Stage 1 (Semantic + Frequency), Grammar Filter, Stage 2 (LM Re-ranking).
+ *
+ * Operates synchronously on pre-loaded data. Each stage gracefully degrades
+ * when its required data isn't available (cold → warm → full warm).
+ */
+export interface ScoringCandidate {
+    authorFreq: number;
+    docFreq: number;
+    sessionFreq: number;
+    tenantFreq: number;
+    word: string;
+}
+export interface ScoredCandidate {
+    finalScore: number;
+    freqScore: number;
+    lmScore: number;
+    semanticScore: number;
+    word: string;
+}
+/** Metadata returned by the grammar filter for debug logging in the caller. */
+export interface GrammarFilterMeta {
+    after: number;
+    before: number;
+    dropped: string[];
+    prevTags: string[];
+    prevWord: string;
+}
+export interface RankCandidatesResult {
+    candidates: ScoredCandidate[];
+    grammarMeta: GrammarFilterMeta | null;
+}
+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/pm-plugins/slow-lane-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Slow Lane Client: Backend context encoding for autocomplete.
+ *
+ * Fires a BE request on word boundaries to encode document context.
+ * Expects the typeahead-encodings API format:
+ *   Request:  { text, session_id }
+ *   Response: { semantic_vector: number[], lm_logits: Record<string, number> }
+ */
+/** Request payload for typeahead-encodings endpoint. */
+export interface TypeaheadEncodingsRequest {
+    session_id: string;
+    text: string;
+}
+/** Response from typeahead-encodings endpoint. */
+export interface TypeaheadEncodingsResponse {
+    lm_logits: Record<string, number>;
+    semantic_vector: number[];
+}
+/**
+ * Check if text ends with a word boundary character (space or punctuation).
+ */
+export declare const isWordBoundary: (text: string) => boolean;
+export interface SlowLaneClientConfig {
+    baseUrl: string;
+    debounceMs?: number;
+    endpoint?: string;
+    fetchFn?: typeof fetch;
+    onUpdate?: (opts: {
+        hasLmLogits: boolean;
+        hasVector: boolean;
+        textLength: number;
+    }) => void;
+    productKey?: string;
+    sessionId?: string;
+}
+export declare const createSlowLaneClient: (config: SlowLaneClientConfig) => {
+    getContextVector: () => Float32Array | null;
+    getLmLogits: () => Record<string, number> | null;
+    isWordBoundary: (text: string) => boolean;
+    setContextVector: (vector: Float32Array | null) => void;
+    setLmLogits: (logits: Record<string, number> | null) => void;
+    updateContext: (text: string) => void;
+};
+export declare const setDefaultSlowLaneClient: (client: ReturnType<typeof createSlowLaneClient> | null) => void;
+export declare const getStoredContextVector: () => Float32Array | null;
+export declare const getStoredLmLogits: () => Record<string, number> | null;

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

@@ -0,0 +1,90 @@
+/**
+ * Fast Lane Predictor: Local autocomplete using weighted trie + frequency + semantic scoring.
+ *
+ * Two prediction modes:
+ *   1. Word boundary → bigram-based next-word suggestion (grammar-filtered)
+ *   2. Mid-word (≥3 chars) → trie prefix search → scoring pipeline → top result
+ *
+ * Scoring is delegated to scoring-pipeline.ts which handles:
+ *   Stage 1 (semantic + frequency), grammar filter, Stage 2 (optional LM re-ranking).
+ *
+ * Context vector: average of word vectors from text before cursor (last N words).
+ * 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.
+ */
+export interface WeightedTerm {
+    authorFreq: number;
+    docFreq: number;
+    freq: number;
+    word: string;
+}
+export interface TenantVocabulary {
+    terms: WeightedTerm[];
+}
+interface VectorStore {
+    dim: number;
+    float32: Float32Array;
+    wordIndex: Record<string, number>;
+}
+/**
+ * Loads the General English vocabulary.
+ * expects a simple array of strings: ["about", "above", "actually", ...]
+ */
+export declare const initL3Vocabulary: (l3Words: string[]) => void;
+/** Enable or disable debug logging. Also checks localStorage key `autocomplete-debug`. */
+export declare const setDebugMode: (enabled: boolean) => void;
+/**
+ * Get predictor status for debugging.
+ * vectorsLoaded: true when semantic scoring is active
+ * wordCount: number of words in vector store (0 if not loaded)
+ */
+export declare const getPredictorStatus: () => {
+    isInitialized: boolean;
+    vectorsLoaded: boolean;
+    vectorsLoadStarted: boolean;
+    wordCount: number;
+};
+/**
+ * Get details of the last prediction (for debugging).
+ * Returns null if no prediction has run yet or debug was off.
+ */
+export declare const getLastPredictionDebug: () => {
+    contextWords: string[];
+    currentWord: string;
+    mode: "cold" | "warm";
+    suggestion: string | null;
+    textBefore: string;
+    topCandidates: Array<{
+        finalScore: number;
+        freqScore: number;
+        lmScore: number;
+        semanticScore: number;
+        word: string;
+    }>;
+} | null;
+export declare const initVocabulary: (vocabulary: TenantVocabulary) => void;
+/**
+ * Increment L1 session frequency for a single word.
+ * Called from the plugin on word boundaries for efficient incremental boosting.
+ */
+export declare const incrementSessionFreq: (word: string) => void;
+/**
+ * Prime session frequencies from a document page string.
+ *
+ * Iterates through every token in `pageContent` and increments its session
+ * frequency so that words already present on the page receive an L1 boost
+ * before the user starts typing.
+ *
+ * Pass `undefined` (or omit the argument) to skip priming — useful when the
+ * calling context does not yet have a page value available.
+ */
+export declare const ingestDocumentPage: (pageContent: string | undefined) => void;
+export declare const predict: (textBefore: string) => string | null;
+export declare const loadVectorsAsync: (options?: {
+    vectorsUrl?: string;
+}) => Promise<void>;
+export declare const initVectors: (store: VectorStore) => void;
+export declare const loadDefaultVocabulary: () => void;
+export {};

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

@@ -1,3 +1,6 @@
-export type AutocompletePlugin = () => {
-    name: 'autocomplete';
-};
+import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { AutocompletePluginOptions, AutocompletePluginState } from './pm-plugins/autocomplete-plugin';
+export type AutocompletePlugin = NextEditorPlugin<'autocomplete', {
+    pluginConfiguration?: AutocompletePluginOptions | undefined;
+    sharedState: AutocompletePluginState | undefined;
+}>;

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

@@ -0,0 +1,36 @@
+import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import { PluginKey } from '@atlaskit/editor-prosemirror/state';
+import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+export declare const autocompletePluginKey: PluginKey<any>;
+export interface AutocompletePluginState {
+    /** The decoration set containing the ghost text widget */
+    decorationSet: DecorationSet;
+    /** The document position where the ghost text should appear */
+    ghostPosition: number;
+    /** The predicted ghost text to display */
+    ghostText: string;
+}
+/**
+ * Context provided to the autocomplete plugin on first editor focus.
+ * Text fields are selectively ingested to boost word-frequency scoring for
+ * predictions, giving words already present in the document/thread an L1
+ * priority boost.
+ */
+export interface AutocompleteContext {
+    /** Full page content as a string (e.g. markdown). */
+    fullPageContent?: string;
+    /** The currently selected text on the page, if any. */
+    pageSelectionContent?: string;
+    /** Content of the parent comment when the editor is in reply or edit mode. */
+    parentCommentContent?: string;
+    /** Contents of sibling comments when the editor is in reply or edit mode. */
+    siblingCommentsContents?: string[];
+}
+export interface AutocompletePluginOptions {
+    /**
+     * Async function called once on first editor focus to retrieve context for
+     * word-frequency boosting. Called lazily so the preset can remain synchronous.
+     */
+    getContext?: () => Promise<AutocompleteContext | undefined>;
+}
+export declare const createAutocompletePlugin: (options?: AutocompletePluginOptions) => SafePlugin<any>;

package/dist/types-ts4.5/pm-plugins/ghost-text-decoration.d.ts

@@ -0,0 +1,7 @@
+import type { EditorState } from '@atlaskit/editor-prosemirror/state';
+import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+/**
+ * Creates a DecorationSet containing a ghost text widget at the given position.
+ * The ghost text is rendered as a styled <span> that appears after the cursor.
+ */
+export declare const createGhostTextDecorationSet: (state: EditorState, position: number, text: string) => DecorationSet;

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

@@ -0,0 +1,33 @@
+/**
+ * Scoring Pipeline: Stage 1 (Semantic + Frequency), Grammar Filter, Stage 2 (LM Re-ranking).
+ *
+ * Operates synchronously on pre-loaded data. Each stage gracefully degrades
+ * when its required data isn't available (cold → warm → full warm).
+ */
+export interface ScoringCandidate {
+    authorFreq: number;
+    docFreq: number;
+    sessionFreq: number;
+    tenantFreq: number;
+    word: string;
+}
+export interface ScoredCandidate {
+    finalScore: number;
+    freqScore: number;
+    lmScore: number;
+    semanticScore: number;
+    word: string;
+}
+/** Metadata returned by the grammar filter for debug logging in the caller. */
+export interface GrammarFilterMeta {
+    after: number;
+    before: number;
+    dropped: string[];
+    prevTags: string[];
+    prevWord: string;
+}
+export interface RankCandidatesResult {
+    candidates: ScoredCandidate[];
+    grammarMeta: GrammarFilterMeta | null;
+}
+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/pm-plugins/slow-lane-client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Slow Lane Client: Backend context encoding for autocomplete.
+ *
+ * Fires a BE request on word boundaries to encode document context.
+ * Expects the typeahead-encodings API format:
+ *   Request:  { text, session_id }
+ *   Response: { semantic_vector: number[], lm_logits: Record<string, number> }
+ */
+/** Request payload for typeahead-encodings endpoint. */
+export interface TypeaheadEncodingsRequest {
+    session_id: string;
+    text: string;
+}
+/** Response from typeahead-encodings endpoint. */
+export interface TypeaheadEncodingsResponse {
+    lm_logits: Record<string, number>;
+    semantic_vector: number[];
+}
+/**
+ * Check if text ends with a word boundary character (space or punctuation).
+ */
+export declare const isWordBoundary: (text: string) => boolean;
+export interface SlowLaneClientConfig {
+    baseUrl: string;
+    debounceMs?: number;
+    endpoint?: string;
+    fetchFn?: typeof fetch;
+    onUpdate?: (opts: {
+        hasLmLogits: boolean;
+        hasVector: boolean;
+        textLength: number;
+    }) => void;
+    productKey?: string;
+    sessionId?: string;
+}
+export declare const createSlowLaneClient: (config: SlowLaneClientConfig) => {
+    getContextVector: () => Float32Array | null;
+    getLmLogits: () => Record<string, number> | null;
+    isWordBoundary: (text: string) => boolean;
+    setContextVector: (vector: Float32Array | null) => void;
+    setLmLogits: (logits: Record<string, number> | null) => void;
+    updateContext: (text: string) => void;
+};
+export declare const setDefaultSlowLaneClient: (client: ReturnType<typeof createSlowLaneClient> | null) => void;
+export declare const getStoredContextVector: () => Float32Array | null;
+export declare const getStoredLmLogits: () => Record<string, number> | null;

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

@@ -0,0 +1,90 @@
+/**
+ * Fast Lane Predictor: Local autocomplete using weighted trie + frequency + semantic scoring.
+ *
+ * Two prediction modes:
+ *   1. Word boundary → bigram-based next-word suggestion (grammar-filtered)
+ *   2. Mid-word (≥3 chars) → trie prefix search → scoring pipeline → top result
+ *
+ * Scoring is delegated to scoring-pipeline.ts which handles:
+ *   Stage 1 (semantic + frequency), grammar filter, Stage 2 (optional LM re-ranking).
+ *
+ * Context vector: average of word vectors from text before cursor (last N words).
+ * 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.
+ */
+export interface WeightedTerm {
+    authorFreq: number;
+    docFreq: number;
+    freq: number;
+    word: string;
+}
+export interface TenantVocabulary {
+    terms: WeightedTerm[];
+}
+interface VectorStore {
+    dim: number;
+    float32: Float32Array;
+    wordIndex: Record<string, number>;
+}
+/**
+ * Loads the General English vocabulary.
+ * expects a simple array of strings: ["about", "above", "actually", ...]
+ */
+export declare const initL3Vocabulary: (l3Words: string[]) => void;
+/** Enable or disable debug logging. Also checks localStorage key `autocomplete-debug`. */
+export declare const setDebugMode: (enabled: boolean) => void;
+/**
+ * Get predictor status for debugging.
+ * vectorsLoaded: true when semantic scoring is active
+ * wordCount: number of words in vector store (0 if not loaded)
+ */
+export declare const getPredictorStatus: () => {
+    isInitialized: boolean;
+    vectorsLoaded: boolean;
+    vectorsLoadStarted: boolean;
+    wordCount: number;
+};
+/**
+ * Get details of the last prediction (for debugging).
+ * Returns null if no prediction has run yet or debug was off.
+ */
+export declare const getLastPredictionDebug: () => {
+    contextWords: string[];
+    currentWord: string;
+    mode: "cold" | "warm";
+    suggestion: string | null;
+    textBefore: string;
+    topCandidates: Array<{
+        finalScore: number;
+        freqScore: number;
+        lmScore: number;
+        semanticScore: number;
+        word: string;
+    }>;
+} | null;
+export declare const initVocabulary: (vocabulary: TenantVocabulary) => void;
+/**
+ * Increment L1 session frequency for a single word.
+ * Called from the plugin on word boundaries for efficient incremental boosting.
+ */
+export declare const incrementSessionFreq: (word: string) => void;
+/**
+ * Prime session frequencies from a document page string.
+ *
+ * Iterates through every token in `pageContent` and increments its session
+ * frequency so that words already present on the page receive an L1 boost
+ * before the user starts typing.
+ *
+ * Pass `undefined` (or omit the argument) to skip priming — useful when the
+ * calling context does not yet have a page value available.
+ */
+export declare const ingestDocumentPage: (pageContent: string | undefined) => void;
+export declare const predict: (textBefore: string) => string | null;
+export declare const loadVectorsAsync: (options?: {
+    vectorsUrl?: string;
+}) => Promise<void>;
+export declare const initVectors: (store: VectorStore) => void;
+export declare const loadDefaultVocabulary: () => void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-autocomplete",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Client-side text autocomplete plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -33,7 +33,7 @@
 		"wink-nlp": "^2.4.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^112.14.0",
+		"@atlaskit/editor-common": "^112.16.0",
 		"react": "^18.2.0"
 	},
 	"techstack": {

package/src/autocompletePlugin.tsx

@@ -1,7 +1,27 @@
-// This file will contain the autocomplete plugin implementation.
-// The full implementation will be added in a follow-up PR.
 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 = () => ({
-	name: 'autocomplete',
-});
+export const autocompletePlugin: AutocompletePlugin = ({ config: options }) => {
+	return {
+		name: 'autocomplete',
+		getSharedState(editorState): AutocompletePluginState | undefined {
+			if (!editorState) {
+				return undefined;
+			}
+			return autocompletePluginKey.getState(editorState) as AutocompletePluginState | undefined;
+		},
+
+		pmPlugins() {
+			return [
+				{
+					name: 'autocomplete',
+					plugin: () => createAutocompletePlugin(options),
+				},
+			];
+		},
+	};
+};

package/src/autocompletePluginType.ts

@@ -1,3 +1,14 @@
-// This file will contain the autocomplete plugin type definitions.
-// The full implementation will be added in a follow-up PR.
-export type AutocompletePlugin = () => { name: 'autocomplete' };
+import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
+
+import type {
+	AutocompletePluginOptions,
+	AutocompletePluginState,
+} from './pm-plugins/autocomplete-plugin';
+
+export type AutocompletePlugin = NextEditorPlugin<
+	'autocomplete',
+	{
+		pluginConfiguration?: AutocompletePluginOptions | undefined;
+		sharedState: AutocompletePluginState | undefined;
+	}
+>;

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

@@ -0,0 +1,15 @@
+{
+  "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",
+  "sideEffects": false,
+  "types": "../../../dist/types/pm-plugins/autocomplete-plugin.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../../../dist/types-ts4.5/pm-plugins/autocomplete-plugin.d.ts"
+      ]
+    }
+  }
+}