@atlaskit/editor-plugin-autocomplete 9.0.0 → 9.2.0

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

@@ -30,6 +30,17 @@ export interface CommittedSuggestion {
     posterior: number;
     /** Final confidence-v2 ranking score. */
     rankScore: number;
+    /**
+     * Characters of already-typed prefix the insertion overwrites, for surfaces
+     * that carry their own casing.
+     *
+     * The scored path appends its tail and leaves what the user typed alone,
+     * which is right for prose. A harvested identifier is matched
+     * case-insensitively but is only correct in the casing it was written in, so
+     * accepting `ml-s` against `ML-Studio` has to replace rather than append.
+     * Absent on every other path.
+     */
+    replacesTypedPrefixLength?: number;
     /** Monotonic editor decision revision that owns this suggestion. */
     revision: number;
     /** How many scored candidates this surface's normaliser divided between. */
@@ -58,6 +69,21 @@ export interface AutocompletePluginState {
  * priority boost.
  */
 export interface AutocompleteContext {
+    /**
+     * Identifies what this context belongs to, for hosts whose editor outlives
+     * the thing it is writing about — a chat input that stays mounted across
+     * conversations and pages, say.
+     *
+     * When it changes, everything learned for the previous scope is dropped:
+     * both the L1 boosts and the harvested inline-code set are claims about what
+     * is being discussed, and neither transfers. The context reported alongside
+     * the new key is then ingested as if it were the first, so anything still
+     * current — an ongoing transcript, for instance — is primed again.
+     *
+     * Omit it and nothing resets; the editor learns for its own lifetime, which
+     * is right for a host mounted per comment or per page.
+     */
+    contextScopeKey?: string;
     /** Full page content as a string (e.g. markdown). */
     fullPageContent?: string;
     /** The currently selected text on the page, if any. */
@@ -73,6 +99,17 @@ export interface AutocompletePluginOptions {
      * word-frequency boosting. Called lazily so the preset can remain synchronous.
      */
     getContext?: () => Promise<AutocompleteContext | undefined>;
+    /**
+     * Opt in to suggesting inline-code identifiers seen in this session
+     * (`ml-studio` and friends), which no vocabulary holds and the scored path
+     * therefore cannot reach.
+     *
+     * Off by default and passed only by hosts whose own experiment enrolment
+     * covers it, so a surface that shares this plugin under a different gate is
+     * unaffected until it opts in too. The harvester is a separate chunk and is
+     * not requested at all while this is false.
+     */
+    harvestInlineCode?: boolean;
     /**
      * User locale used to determine whether autocomplete should run.
      * Defaults to browser locale when omitted.

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

@@ -25,9 +25,29 @@ declare global {
              * `__atlCtcDebug__.enable('verbose')`.
              */
             enable: (level?: 'verbose') => void;
+            /**
+             * Snapshot of the inline-code surfaces harvested this session, or what a
+             * typed prefix would be offered: `__atlCtcDebug__.harvest('ml-s')`.
+             *
+             * Installed by the harvester 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. Undefined
+             * until the harvester chunk has loaded.
+             */
+            harvest?: (typedPrefix?: string) => unknown;
             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 for the same reasons as `harvest` above, and
+             * distinct from it: this reports known words whose frequency the session
+             * raised, while `harvest` holds surfaces the vocabulary does not have.
+             */
+            session?: (prefix?: string) => unknown;
         };
     }
 }
@@ -60,3 +80,17 @@ 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 harvest 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 registerCtcHarvestInspector: (inspect: (typedPrefix?: string) => unknown) => void;
+/**
+ * Hang the L1 session-boost snapshot off the console API, on the same terms as
+ * `registerCtcHarvestInspector`: available whether or not logging is on.
+ */
+export declare const registerCtcSessionInspector: (inspect: (prefix?: string) => unknown) => void;

package/dist/types/pm-plugins/inline-code-harvester.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Inline-code harvester — the Class B candidate source.
+ *
+ * Class A terms (Atlassian, Confluence) already carry tenant frequencies, a word
+ * vector and canonical token ids, so they compete inside the scored pool. Class B
+ * terms — `ml-studio` and friends — exist only in the session and cannot be
+ * suggested at all today: `incrementSessionFreq` only touches trie nodes that
+ * already exist, so an unknown session word is silently discarded.
+ *
+ * Two sources carry the signal. Assistant replies arrive as markdown strings and
+ * keep their backticks; the live document has had its backticks consumed by the
+ * text-formatting input rule, so its spans are found through the `code` mark
+ * instead. Human chat messages arrive as ADF and are flattened to bare text, so
+ * they contribute no spans — which is why no author check is needed here.
+ *
+ * A harvested surface cannot be scored: there is no frequency to rank it, no
+ * vector to place it in context and no canonical token ids to price it under the
+ * model. Being marked as code is the whole of the evidence, so what stands in for
+ * a score is where the surface is allowed to speak — only on a prefix no
+ * vocabulary reached, and only once the scored path has finished with it.
+ *
+ * Sightings are still counted, per source and by different rules, but they do
+ * not admit a surface. They order the set under eviction, and they pick between
+ * two surfaces that complete the same typed prefix — see `HarvestedTerm` and
+ * `findHarvestedCompletion`.
+ *
+ * What the session is holding is visible at any time from the console:
+ * `__atlCtcDebug__.harvest()`, or `__atlCtcDebug__.harvest('ml-s')` to ask what
+ * a prefix would be offered — see `inspectInlineCodeHarvest`.
+ */
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+/** Why this surface was chosen over the others that completed the prefix. */
+export type HarvestCollapseRule = 'alphabetical' | 'sightings' | 'sole-match';
+export interface HarvestMatch {
+    /** Which rule settled the prefix; `sole-match` when there was no rival. */
+    collapsedBy: HarvestCollapseRule;
+    /** Code-marked spans in the document, as of the last walk. */
+    documentSpans: number;
+    /** Characters of the surface the user has not typed yet. */
+    ghostText: string;
+    /** Mentions across ingested reply and page text. */
+    replyOccurrences: number;
+    /** Surfaces that also completed the prefix and lost, in the losing order. */
+    rivalSurfaces: string[];
+    /** Full surface in its original casing, which replaces the typed prefix. */
+    surface: string;
+    /** Length of the typed prefix the surface replaces on accept. */
+    typedPrefixLength: number;
+}
+interface HarvestFunnel {
+    accepted: number;
+    rejectedInFence: number;
+    rejectedKnownL2: number;
+    rejectedKnownL3: number;
+    rejectedNonAlphaStart: number;
+    rejectedTooLong: number;
+    rejectedWhitespace: number;
+    spansFound: number;
+}
+/**
+ * Harvest single-backtick spans from a markdown-ish string. Fenced regions are
+ * skipped: they hold commands and file paths, and their contents are whitespace
+ * separated anyway.
+ */
+export declare const harvestInlineCodeFromText: (text: string | undefined) => void;
+/**
+ * Harvest code-marked text from the live document. The backtick input rule fires
+ * on the closing tick and removes both delimiters, so a finished span is only
+ * findable through its mark. Code blocks are skipped for the same reason fenced
+ * regions are.
+ *
+ * The whole document is re-read, and what it finds replaces the previous
+ * document counts rather than adding to them.
+ */
+export declare const harvestInlineCodeFromDoc: (doc: PMNode) => void;
+/**
+ * The harvested surface to offer for `typedPrefix`, or null.
+ *
+ * Rivals are collapsed rather than treated as a reason to stay quiet. Silence
+ * was the original rule, on the grounds that two session surfaces sharing a
+ * prefix have nothing to separate them, and it was wrong for the case this path
+ * exists to serve: a reply that answers "what are our services" names ten of
+ * them, several share a stem, and abstaining meant the harvester went quiet on
+ * exactly the reply it was built for. Being wrong here costs one keystroke —
+ * the ghost is ignored and typing continues — and staying silent costs the
+ * feature.
+ *
+ * `collapsedBy` records which rule settled it so a surprising ghost can be
+ * explained after the fact rather than guessed at.
+ */
+export declare const findHarvestedCompletion: (typedPrefix: string) => HarvestMatch | null;
+interface HarvestTermSnapshot {
+    /** Code-marked spans in the document as of the last walk. */
+    documentSpans: number;
+    /** Whether the surface is long enough to ever produce a ghost. */
+    longEnough: boolean;
+    /** Whether a sighting still stands behind it. */
+    offerable: boolean;
+    /** Mentions across ingested reply and page text. */
+    replyOccurrences: number;
+    /** Sum of both sources, which is what collapses rivals. */
+    sightings: number;
+    surface: string;
+}
+export interface HarvestSnapshot {
+    /** Size the set is held to; beyond it the weakest surfaces are dropped. */
+    cap: number;
+    /** How many surfaces have been dropped to hold the cap this session. */
+    evicted: number;
+    /**
+     * Intake accounting per source. The context funnel accumulates over the
+     * session; the live-document funnel describes the most recent walk only.
+     */
+    funnels: {
+        context: HarvestFunnel;
+        liveDocument: HarvestFunnel;
+    };
+    /**
+     * What a typed prefix would be offered, when one was passed.
+     *
+     * The harvester's own answer, not a prediction of what will appear on screen:
+     * the plugin still has to find the scored path finished and empty on that
+     * prefix, and still applies the accept cooldown and the repetition check.
+     */
+    match?: HarvestMatch | null;
+    /** The whole set in collapse order, so the winner for any prefix is above its rivals. */
+    terms: HarvestTermSnapshot[];
+}
+/**
+ * Read the session's harvest, optionally asking what `typedPrefix` would get.
+ *
+ * Installed as `__atlCtcDebug__.harvest()` and returned rather than logged, so
+ * the console renders it as an inspectable object and a caller can assert on it.
+ */
+export declare const inspectInlineCodeHarvest: (typedPrefix?: string) => HarvestSnapshot;
+export declare const resetInlineCodeHarvest: () => void;
+/**
+ * Print the funnel when it has moved since the last print.
+ *
+ * Deliberately reports zero-span and all-rejected passes too. Logging only on a
+ * successful harvest makes "the replies held no inline code", "every span was
+ * filtered out" and "this never ran" indistinguishable, which are the three
+ * things worth telling apart.
+ */
+export declare const logInlineCodeHarvest: (trigger: string) => void;
+export {};

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

@@ -12,9 +12,41 @@
  * 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';
+/**
+ * Which constraint stopped an evaluation from putting a ghost on screen.
+ *
+ * Each one implies different work: `below-posterior-gate` is a threshold to
+ * calibrate, `winner-margin` is two candidates the model cannot separate,
+ * `cold-competitor` and `unresolved-rival` are scheduling, and `no-candidate`
+ * is vocabulary coverage.
+ */
+export type CtcAbstainReason = 'below-posterior-gate' | 'cold-competitor' | 'empty-completion' | 'implausible-surface' | 'lone-candidate' | 'missing-artifact' | 'no-candidate' | 'no-evidence' | 'no-surface-token' | 'not-initialized' | 'prefetch' | 'short-completion' | 'unresolved-rival' | 'winner-margin';
+/**
+ * What the scored path concluded, recorded on every evaluation whether or not
+ * debug is on.
+ *
+ * This exists for the inline-code harvester, which may only offer a harvested
+ * surface once the scored path has finished and come away empty. The reason is
+ * the load-bearing part: `no-candidate` means no vocabulary reaches this prefix
+ * at all, while `winner-margin` means two known words the model cannot yet
+ * separate — the first is a gap worth filling and the second is a prefix
+ * ambiguous enough that filling it would be a guess.
+ */
+export interface PredictionOutcome {
+    abstainReason: CtcAbstainReason | null;
+    /** True while a pending async signal could still change the verdict. */
+    awaitingAsyncEvidence: boolean;
+    /** How many vocabulary candidates were scored for this prefix. */
+    scoredCandidateCount: number;
+    /** The exact string passed to `predict`, so a caller can confirm identity. */
+    textBefore: string;
+}
 export interface WeightedTerm {
     authorFreq: number;
     docFreq: number;
@@ -34,12 +66,24 @@ interface VectorStore {
  * expects a simple array of strings: ["about", "above", "actually", ...]
  */
 export declare const initL3Vocabulary: (l3Words: string[]) => void;
+/** The verdict from the most recent `predict` call. Always populated. */
+export declare const getLastPredictionOutcome: () => PredictionOutcome | null;
 /**
  * Start a short cooldown for the exact surface the editor inserted. The caller
  * passes the committed snapshot's surface so background re-ranking can never
  * move cooldown bookkeeping away from what the user actually accepted.
  */
 export declare const noteSuggestionAccepted: (surface: string) => void;
+/**
+ * Whether `surface` is the one the user just accepted and is still inside its
+ * cooldown window.
+ *
+ * Read-only, unlike the advance inside `predict`: the cooldown is measured in
+ * predictions, and a caller asking whether it is active must not consume one of
+ * them. Exported for the harvest path, which displays without going through
+ * arbitration and so would otherwise re-offer what was just accepted.
+ */
+export declare const isSurfaceInAcceptCooldown: (surface: string) => boolean;
 /**
  * Get predictor status for debugging.
  * vectorsLoaded: true when semantic scoring is active
@@ -100,6 +144,24 @@ export declare const initPhrases: (artifact: PhraseArtifactJson, termType: TermT
  * Called from the plugin on word boundaries for efficient incremental boosting.
  */
 export declare const incrementSessionFreq: (word: string) => void;
+/**
+ * Drop every L1 boost this session has accumulated.
+ *
+ * The vocabulary itself is left alone: only `sessionFreq` is cleared, so the
+ * tenant and generic frequencies a boost was sitting on top of survive. Called
+ * when the plugin decides the session it was learning for has ended — a new
+ * conversation, or a different page — since a boost is a claim about what is
+ * being discussed and that claim does not carry over.
+ */
+export declare const resetSessionBoosts: () => void;
+/**
+ * Which vocabulary already holds this surface, if any.
+ *
+ * Used by the inline-code harvester to drop terms the scored path can already
+ * serve, so that harvesting stays limited to words with no route to a
+ * suggestion today.
+ */
+export declare const lookupVocabularySource: (word: string) => 'l2' | 'l3' | null;
 /**
  * Prime session frequencies from a document page string.
  *
@@ -111,6 +173,39 @@ 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 — that gap is what the inline-code harvester covers, and those surfaces show
+ * up under `__atlCtcDebug__.harvest()` instead.
+ */
+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.
@@ -123,8 +218,15 @@ export interface PredictionResult {
         verifiedChars: number;
         verifiedTokens: number;
     };
-    /** Evidence tier that authorized display. Tier A is never display-eligible. */
-    evidenceTier: 'canonical-full-surface' | 'network-logit';
+    /**
+     * Evidence tier that authorized display. Tier A is never display-eligible.
+     *
+     * `session-harvest` never passes through this module: an inline-code surface
+     * harvested from the session has no frequencies, vector or canonical token
+     * ids, so it is authorized by being marked as code on a prefix the scored
+     * path left unclaimed rather than by model evidence.
+     */
+    evidenceTier: 'canonical-full-surface' | 'network-logit' | 'session-harvest';
     /**
      * Mean per-token log-probability of the verified prefix.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-autocomplete",
-	"version": "9.0.0",
+	"version": "9.2.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.13.0",
 		"@atlaskit/editor-plugin-analytics": "^15.0.0",
 		"react": "^18.2.0 || ^19.2.0"
 	},