@atlaskit/editor-plugin-limited-mode 13.0.18 → 14.1.0

package/dist/types/pm-plugins/utils/latch-policy.d.ts

@@ -0,0 +1,112 @@
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+import type { LatchDetails, LatchEvaluation, LatchPolicyConfig, LatchPolicyOptions } from './latch-policy-types';
+/**
+ * The shipped policy.
+ *
+ * These values add up to: nothing counts for the first 10s; then a window qualifies on either 6 of
+ * 12 keystrokes slower than 100ms with that window's median also over 100ms, or 3 long tasks over
+ * 600ms within 30s corroborated by a slow keystroke in that same 30s. Two qualifying windows at
+ * least 30s apart latch limited mode.
+ *
+ * `freezeTaskMs` matches `DEFAULT_FREEZE_THRESHOLD` in
+ * `editor-plugin-base/src/pm-plugins/frozen-editor.ts`, which backs the existing
+ * `ACTION.BROWSER_FREEZE` telemetry, so production dashboards can be used to calibrate it.
+ * `slowInputMs` is deliberately tighter than that file's `DEFAULT_SLOW_THRESHOLD` of 300 — this
+ * needs to notice a degraded experience, not just an unusable one.
+ *
+ * `requiredConfirmations` and `confirmationGapMs` are the values that matter most — see the comment
+ * on the former.
+ */
+export declare const DEFAULT_LATCH_POLICY_CONFIG: LatchPolicyConfig;
+/**
+ * Decides whether limited mode should be on.
+ *
+ * The single authority for that question, covering both reasons:
+ *
+ * - **The document** — too large, too many nodes, or containing a legacy content macro. Evaluated on
+ *   load and on document replacement, so it can turn back off (a `replaceDocument` onto a smaller
+ *   page) without costing a full-document walk per transaction.
+ * - **The device** — sustained slow keystrokes or repeated long tasks. **One-way**: once the runtime
+ *   bar is met the policy stops evaluating, so the editor can never oscillate between modes.
+ *
+ * `isBreached()` is the combined verdict. Everything tunable is in `config`, so the whole high bar is
+ * unit-testable without needing to make a real browser slow, and a caller can substitute a
+ * differently configured policy. `latch-detector.ts` owns the browser plumbing that feeds the runtime
+ * criteria, and takes a policy instance rather than constructing one.
+ */
+export declare class LatchPolicy {
+    /** Public so the detector can read the tunables it needs rather than duplicating them. */
+    readonly config: LatchPolicyConfig;
+    /** Public so the detector shares one clock with the policy. */
+    readonly now: () => number;
+    private readonly startedAt;
+    private latencySamples;
+    private freezeTimes;
+    private lastSlowInputAt;
+    private firstQualifiedAt;
+    private lastQualifiedAt;
+    private qualifiedWindows;
+    private suppressedUntil;
+    private latched;
+    private documentBreached;
+    private firstWindowReason;
+    private latchDetails;
+    /** Cumulative for the session and never cleared, unlike the evidence buffers. */
+    private totalInputSamples;
+    private totalSlowInputs;
+    private totalFreezes;
+    constructor({ now, config }: LatchPolicyOptions);
+    /**
+     * Whether limited mode should be on, for either reason. This is the verdict consumers act on.
+     */
+    isBreached(): boolean;
+    /**
+     * What the latch was based on, or `undefined` while un-latched. Intended for telemetry — nothing in
+     * the decision reads it back.
+     */
+    getLatchDetails(): LatchDetails | undefined;
+    /** Whether the runtime (device) criteria have latched. One-way, and never cleared. */
+    isLatched(): boolean;
+    /**
+     * Latch the runtime reason directly, without accumulating evidence for it.
+     *
+     * The policy latches itself when its own criteria are met, so this exists for callers that have
+     * already decided: the plugin replaying the detector's latch transaction, and dev tooling forcing
+     * the state by hand. Idempotent, and one-way like every other route to `latched`.
+     */
+    latch(): void;
+    /** Whether the document currently breaches the thresholds. Can go back to false. */
+    isDocumentBreached(): boolean;
+    /**
+     * Evaluate the document reason against the size / node-count / legacy-content-macro thresholds.
+     *
+     * Walks the whole document, so the caller decides when it is worth paying for: `pm-plugins/main.ts`
+     * calls this on load and on `replaceDocument` (e.g. live-to-live page navigation) only, never per
+     * transaction. Editing therefore cannot turn the document reason on — a page that grows past the
+     * thresholds mid-session is only re-judged the next time it loads — but replacement can still turn
+     * it back off.
+     */
+    evaluateDocument(doc: PMNode): void;
+    /**
+     * Whether a `doc.nodeSize` delta is large enough to be bulk work rather than typing. A keystroke
+     * moves this by 1; a paste, a bulk replace or a document load moves it far more.
+     */
+    isBulkChange(nodeSizeDelta: number): boolean;
+    /**
+     * Discard signals for a window. Called for bulk work, which is expensive but transient and
+     * self-limiting, so its cost must not be attributed to the device struggling.
+     */
+    suppress(): void;
+    /**
+     * Feed one keystroke's input latency (dispatch through to the next animation frame).
+     */
+    recordInputLatency(durationMs: number): LatchEvaluation;
+    /**
+     * Feed one `longtask` PerformanceObserver entry.
+     */
+    recordLongTask(durationMs: number): LatchEvaluation;
+    private canRecord;
+    /** Snapshot of what the latch was based on. Called before the evidence buffers are cleared. */
+    private buildDetails;
+    private qualify;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-limited-mode",
-	"version": "13.0.18",
+	"version": "14.1.0",
 	"description": "LimitedMode plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -20,18 +20,22 @@
 	"sideEffects": false,
 	"atlaskit:src": "src/index.ts",
 	"dependencies": {
+		"@atlaskit/editor-plugin-analytics": "^17.0.0",
 		"@atlaskit/editor-prosemirror": "^8.0.0",
+		"@atlaskit/feature-gate-js-client": "^6.0.0",
+		"@atlaskit/platform-feature-experiments": "^0.3.0",
 		"@atlaskit/platform-feature-flags": "^2.2.0",
-		"@atlaskit/tmp-editor-statsig": "^178.0.0",
+		"@atlaskit/tmp-editor-statsig": "^179.0.0",
 		"@babel/runtime": "^7.0.0",
 		"bind-event-listener": "^3.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^120.16.0",
+		"@atlaskit/editor-common": "^121.1.0",
 		"react": "^18.2.0 || ^19.2.0",
 		"react-intl": "^5.25.1 || ^6.0.0 || ^7.0.0"
 	},
 	"devDependencies": {
+		"@atlassian/experiment-test-utils": "^0.2.0",
 		"react": "^19.2.0",
 		"react-intl": "^7.0.0",
 		"typescript": "npm:@typescript/typescript6@^6.0.2"