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

package/dist/esm/pm-plugins/utils/latch-policy.js

@@ -0,0 +1,307 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+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 { median } from '@atlaskit/editor-common/median';
+import { shouldEnableLimitedModeForDocument } from '@atlaskit/editor-common/should-enable-limited-mode';
+/**
+ * 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 var DEFAULT_LATCH_POLICY_CONFIG = {
+  warmUpMs: 10000,
+  slowInputMs: 100,
+  latencyWindowSize: 12,
+  latencySlowSamplesRequired: 6,
+  freezeTaskMs: 600,
+  freezeTasksRequired: 3,
+  freezeWindowMs: 30000,
+  requiredConfirmations: 2,
+  confirmationGapMs: 30000,
+  bulkChangeNodeSize: 100,
+  bulkChangeSuppressionMs: 2000,
+  docSizeThreshold: 750000,
+  nodeCountThreshold: 5000
+};
+
+/**
+ * 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 var LatchPolicy = /*#__PURE__*/function () {
+  function LatchPolicy(_ref) {
+    var now = _ref.now,
+      config = _ref.config;
+    _classCallCheck(this, LatchPolicy);
+    /** Public so the detector can read the tunables it needs rather than duplicating them. */
+    /** Public so the detector shares one clock with the policy. */
+    _defineProperty(this, "latencySamples", []);
+    _defineProperty(this, "freezeTimes", []);
+    _defineProperty(this, "qualifiedWindows", 0);
+    _defineProperty(this, "suppressedUntil", 0);
+    _defineProperty(this, "latched", false);
+    _defineProperty(this, "documentBreached", false);
+    /** Cumulative for the session and never cleared, unlike the evidence buffers. */
+    _defineProperty(this, "totalInputSamples", 0);
+    _defineProperty(this, "totalSlowInputs", 0);
+    _defineProperty(this, "totalFreezes", 0);
+    this.now = now;
+    this.config = _objectSpread(_objectSpread({}, DEFAULT_LATCH_POLICY_CONFIG), config);
+    this.startedAt = now();
+  }
+
+  /**
+   * Whether limited mode should be on, for either reason. This is the verdict consumers act on.
+   */
+  return _createClass(LatchPolicy, [{
+    key: "isBreached",
+    value: function isBreached() {
+      return this.documentBreached || this.latched;
+    }
+
+    /**
+     * What the latch was based on, or `undefined` while un-latched. Intended for telemetry — nothing in
+     * the decision reads it back.
+     */
+  }, {
+    key: "getLatchDetails",
+    value: function getLatchDetails() {
+      return this.latchDetails;
+    }
+
+    /** Whether the runtime (device) criteria have latched. One-way, and never cleared. */
+  }, {
+    key: "isLatched",
+    value: function isLatched() {
+      return this.latched;
+    }
+
+    /**
+     * 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`.
+     */
+  }, {
+    key: "latch",
+    value: function latch() {
+      if (this.latched) {
+        return;
+      }
+      this.latched = true;
+      this.latchDetails = this.buildDetails('forced', undefined);
+    }
+
+    /** Whether the document currently breaches the thresholds. Can go back to false. */
+  }, {
+    key: "isDocumentBreached",
+    value: function isDocumentBreached() {
+      return this.documentBreached;
+    }
+
+    /**
+     * 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.
+     */
+  }, {
+    key: "evaluateDocument",
+    value: function evaluateDocument(doc) {
+      this.documentBreached = shouldEnableLimitedModeForDocument(doc, {
+        docSizeThreshold: this.config.docSizeThreshold,
+        nodeCountThreshold: this.config.nodeCountThreshold
+      });
+    }
+
+    /**
+     * 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.
+     */
+  }, {
+    key: "isBulkChange",
+    value: function isBulkChange(nodeSizeDelta) {
+      return Math.abs(nodeSizeDelta) >= this.config.bulkChangeNodeSize;
+    }
+
+    /**
+     * 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.
+     */
+  }, {
+    key: "suppress",
+    value: function suppress() {
+      if (this.latched) {
+        return;
+      }
+      this.suppressedUntil = this.now() + this.config.bulkChangeSuppressionMs;
+    }
+
+    /**
+     * Feed one keystroke's input latency (dispatch through to the next animation frame).
+     */
+  }, {
+    key: "recordInputLatency",
+    value: function recordInputLatency(durationMs) {
+      if (!this.canRecord()) {
+        return 'ignored';
+      }
+      var _this$config = this.config,
+        slowInputMs = _this$config.slowInputMs,
+        latencyWindowSize = _this$config.latencyWindowSize,
+        latencySlowSamplesRequired = _this$config.latencySlowSamplesRequired;
+      this.totalInputSamples += 1;
+      if (durationMs > slowInputMs) {
+        this.totalSlowInputs += 1;
+        // Remembered even once the window rolls over, so the freeze criterion below can check that
+        // the jank actually coincided with editing.
+        this.lastSlowInputAt = this.now();
+      }
+      this.latencySamples.push(durationMs);
+      if (this.latencySamples.length > latencyWindowSize) {
+        this.latencySamples.shift();
+      }
+      if (this.latencySamples.length < latencyWindowSize) {
+        return 'recorded';
+      }
+      var slowSamples = this.latencySamples.filter(function (sample) {
+        return sample > slowInputMs;
+      }).length;
+      if (slowSamples < latencySlowSamplesRequired) {
+        return 'recorded';
+      }
+
+      // Median rather than mean: a mean is dragged over the threshold by one or two outliers, which
+      // is exactly the transient jank this policy is meant to ignore.
+      var windowMedian = median(this.latencySamples);
+      if (windowMedian <= slowInputMs) {
+        return 'recorded';
+      }
+      return this.qualify('inputLatency', windowMedian);
+    }
+
+    /**
+     * Feed one `longtask` PerformanceObserver entry.
+     */
+  }, {
+    key: "recordLongTask",
+    value: function recordLongTask(durationMs) {
+      if (!this.canRecord()) {
+        return 'ignored';
+      }
+      var _this$config2 = this.config,
+        freezeTaskMs = _this$config2.freezeTaskMs,
+        freezeWindowMs = _this$config2.freezeWindowMs,
+        freezeTasksRequired = _this$config2.freezeTasksRequired;
+      if (durationMs <= freezeTaskMs) {
+        return 'recorded';
+      }
+      var now = this.now();
+      this.totalFreezes += 1;
+      this.freezeTimes.push(now);
+      this.freezeTimes = this.freezeTimes.filter(function (time) {
+        return now - time <= freezeWindowMs;
+      });
+      if (this.freezeTimes.length < freezeTasksRequired) {
+        return 'recorded';
+      }
+
+      // Corroboration. `longtask` is process-wide, so without this a busy background tab or an
+      // unrelated app could latch an editor the user is typing in perfectly happily.
+      if (this.lastSlowInputAt === undefined || now - this.lastSlowInputAt > freezeWindowMs) {
+        return 'recorded';
+      }
+      return this.qualify('freeze');
+    }
+  }, {
+    key: "canRecord",
+    value: function canRecord() {
+      if (this.latched) {
+        return false;
+      }
+      var now = this.now();
+      if (now - this.startedAt < this.config.warmUpMs) {
+        return false;
+      }
+      return now >= this.suppressedUntil;
+    }
+
+    /** Snapshot of what the latch was based on. Called before the evidence buffers are cleared. */
+  }, {
+    key: "buildDetails",
+    value: function buildDetails(reason, latencyMedianMs) {
+      var _this$firstWindowReas;
+      var now = this.now();
+      return {
+        reason: reason,
+        firstWindowReason: (_this$firstWindowReas = this.firstWindowReason) !== null && _this$firstWindowReas !== void 0 ? _this$firstWindowReas : reason,
+        requiredConfirmations: this.config.requiredConfirmations,
+        documentAlreadyBreached: this.documentBreached,
+        msFromFirstWindow: this.firstQualifiedAt === undefined ? undefined : Math.round(now - this.firstQualifiedAt),
+        latencyMedianMs: latencyMedianMs === undefined ? undefined : Math.round(latencyMedianMs),
+        timeToLatchMs: Math.round(now - this.startedAt),
+        totalInputSamples: this.totalInputSamples,
+        totalSlowInputs: this.totalSlowInputs,
+        totalFreezes: this.totalFreezes
+      };
+    }
+  }, {
+    key: "qualify",
+    value: function qualify(reason, latencyMedianMs) {
+      var now = this.now();
+
+      // Each qualifying window must be independent evidence, so the buffers are cleared rather than
+      // left to re-trigger off the same samples on the very next keystroke.
+      this.latencySamples = [];
+      this.freezeTimes = [];
+
+      // Too soon after the last counted window to be independent of it, so it earns no credit. The
+      // buffers above are still cleared, which is what makes the run rebuild from scratch.
+      if (this.lastQualifiedAt !== undefined && now - this.lastQualifiedAt < this.config.confirmationGapMs) {
+        return 'qualified';
+      }
+      this.qualifiedWindows += 1;
+      this.lastQualifiedAt = now;
+      if (this.firstQualifiedAt === undefined) {
+        this.firstQualifiedAt = now;
+        this.firstWindowReason = reason;
+      }
+      if (this.qualifiedWindows < this.config.requiredConfirmations) {
+        return 'qualified';
+      }
+      this.latched = true;
+      this.latchDetails = this.buildDetails(reason, latencyMedianMs);
+      return 'latched';
+    }
+  }]);
+}();

package/dist/types/limitedModePluginType.d.ts

@@ -1,10 +1,43 @@
 import type React from 'react';
-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 { PluginKey } from '@atlaskit/editor-prosemirror/state';
 export type LimitedModePluginState = {
+    /**
+     * The document itself breaches the size / node-count / legacy-content thresholds.
+     *
+     * Recomputed from the document, and deliberately re-evaluated when the document is replaced
+     * (live-to-live page navigation), so navigating from a huge page to a small one restores the full
+     * feature set.
+     */
     documentSizeBreachesThreshold: boolean;
+    /**
+     * Whether limited mode is in force — the single flag every consumer should branch on.
+     *
+     * Derived from the reasons below and kept in state deliberately, so that consumers do not have to
+     * know what the reasons are or how they combine. Adding a future reason then needs no change
+     * outside this plugin.
+     */
+    enabled: boolean;
+    /**
+     * The latch policy says limited mode should be on.
+     *
+     * Only meaningful under `platform_editor_dynamic_limited_mode`; `false` in the control arm, where
+     * `documentSizeBreachesThreshold` alone decides. When the experiment is on this is the verdict
+     * `enabled` is taken from, and it covers both of the policy's reasons — the document thresholds
+     * and the runtime device criteria.
+     *
+     * The device half is **one-way**: once the runtime bar is met it is never cleared for the lifetime
+     * of the editor view, including across document replacement, because navigating between pages does
+     * not change the device. That is deliberate — entering or leaving limited mode is itself expensive
+     * (tearing down observers, rebuilding decoration sets), so a recoverable mode would risk
+     * oscillating on borderline devices and being worse than either steady state. A user whose machine
+     * recovers gets the full editor back by reloading the page.
+     */
+    latchPolicyBreached: boolean;
 };
 export type LimitedModePlugin = NextEditorPlugin<'limitedMode', {
+    dependencies: [OptionalPlugin<AnalyticsPlugin>];
     pluginConfiguration: LimitedModePluginOptions | undefined;
     sharedState: {
         enabled: boolean;

package/dist/types/pm-plugins/main.d.ts

@@ -1,5 +1,13 @@
 import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
-import { PluginKey } from '@atlaskit/editor-prosemirror/state';
-import type { LimitedModePluginState } from '../limitedModePluginType';
-export declare const limitedModePluginKey: PluginKey;
-export declare const createPlugin: () => SafePlugin<LimitedModePluginState>;
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
+import type { LimitedModePlugin, LimitedModePluginState } from '../limitedModePluginType';
+import { LatchPolicy } from './utils/latch-policy';
+export declare const createPlugin: (api?: ExtractInjectionAPI<LimitedModePlugin>, 
+/**
+ * Replaces the policy this plugin would build for itself.
+ *
+ * Internal seam for tests that need to drive the criteria against a controlled clock and
+ * thresholds. Production goes through `limitedModePlugin`, which never passes one, so the
+ * experiment still decides whether a policy exists at all.
+ */
+injectedPolicy?: LatchPolicy) => SafePlugin<LimitedModePluginState>;

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

@@ -0,0 +1,2 @@
+import { PluginKey } from '@atlaskit/editor-prosemirror/state';
+export declare const limitedModePluginKey: PluginKey;

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

@@ -0,0 +1,30 @@
+import type { LatchDetails } from './latch-policy-types';
+import type { LatchPolicy } from './latch-policy';
+export type LatchDetector = {
+    destroy: () => void;
+    /**
+     * Call once per text input. Measures the time from the input reaching ProseMirror to the next
+     * animation frame — i.e. dispatch plus all plugin work, before the browser paints.
+     */
+    measureInput: () => void;
+    /**
+     * Report a document change so bulk work can be discounted. The policy decides what counts as
+     * bulk; the caller only supplies the facts.
+     */
+    noteDocumentChange: (change: {
+        isDocumentReplaced: boolean;
+        nodeSizeDelta: number;
+    }) => void;
+};
+export type CreateLatchDetectorOptions = {
+    /**
+     * Invoked at most once, when the high bar is met, with what the latch was based on. The policy
+     * builds that snapshot before clearing its evidence buffers.
+     */
+    onLatchCriteriaMet: (details: LatchDetails) => void;
+    /**
+     * The decision itself. Injected rather than constructed here so a caller can supply a differently
+     * configured policy — and so the detector holds no thresholds of its own.
+     */
+    policy: LatchPolicy;
+};

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

@@ -0,0 +1,15 @@
+import type { CreateLatchDetectorOptions, LatchDetector } from './latch-detector-types';
+/**
+ * Wires browser performance signals into the supplied {@link LatchPolicy}.
+ *
+ * Holds no configuration and makes no decisions: it measures, and forwards. Everything tunable lives
+ * on the policy, including the clock it reads.
+ *
+ * The measurement mirrors `editor-plugin-base/src/pm-plugins/frozen-editor.ts`, which already runs an
+ * identical `longtask` observer and per-keystroke rAF measurement for every session to feed
+ * `ACTION.SLOW_INPUT` / `ACTION.BROWSER_FREEZE`. It is duplicated rather than shared so that this
+ * experiment stays self-contained inside the limited-mode plugin — no new cross-plugin dependency,
+ * and deleting it is a single-directory revert if the experiment does not ship. The marginal cost is
+ * one `performance.now()` and one `requestAnimationFrame` per keystroke.
+ */
+export declare const createLatchDetector: ({ onLatchCriteriaMet, policy, }: CreateLatchDetectorOptions) => LatchDetector;

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

@@ -0,0 +1,150 @@
+/**
+ * Every tunable the latch decision depends on.
+ *
+ * All of it lives here rather than being spread across the detector and the plugin: the numbers *are*
+ * the policy, so a different policy is a different set of these values, and having them in one place
+ * is what makes the trigger reviewable and tunable as a unit.
+ *
+ * Shape of the decision, so the fields below read in context. Two independent criteria can each
+ * close a "qualifying window": sustained slow keystrokes (`slowInputMs`, `latency*`) or repeated
+ * long tasks (`freeze*`). Latching needs `requiredConfirmations` such windows, each separated from
+ * the last by `confirmationGapMs`. `warmUpMs` and `bulkChange*` decide when signals are discarded
+ * rather than counted.
+ */
+export type LatchPolicyConfig = {
+    /**
+     * Smallest absolute `doc.nodeSize` delta, compared inclusively, for a transaction to count
+     * as bulk work rather than typing — a keystroke moves it by 1, a paste or document load far
+     * more. Operations that are expensive but barely change size, such as a table resize or a
+     * drag-and-drop move (delete + insert nets to roughly 0), are not caught by this.
+     */
+    bulkChangeNodeSize: number;
+    /**
+     * How long every signal is discarded once bulk work is reported, measured forward from that
+     * moment. Each new report pushes the deadline out again, so back-to-back bulk changes hold the
+     * window open rather than each getting their own.
+     */
+    bulkChangeSuppressionMs: number;
+    /**
+     * Minimum gap between one qualifying window and the next for the later one to count, compared
+     * inclusively. Measured from the previous *counted* window, so raising `requiredConfirmations`
+     * raises the total time to latch with it. A window arriving sooner earns no credit yet still
+     * clears the evidence buffers, so the run rebuilds from scratch.
+     */
+    confirmationGapMs: number;
+    /**
+     * `doc.nodeSize` above which the document alone puts the editor into limited mode, compared
+     * strictly. A backstop for pathologically large documents rather than a routine trigger — see
+     * `limited-mode-document-thresholds.ts` for the production percentiles behind the shipped value.
+     */
+    docSizeThreshold: number;
+    /** Duration a single long task must exceed to be counted as a freeze. */
+    freezeTaskMs: number;
+    /**
+     * How many freezes must sit inside `freezeWindowMs` for the freeze criterion to qualify. They
+     * only count alongside a recent slow keystroke — see `freezeWindowMs`.
+     */
+    freezeTasksRequired: number;
+    /**
+     * Does two jobs. It is the sliding window freezes are retained in, older entries being pruned by
+     * timestamp on each new freeze; and it is the horizon within which a slow keystroke must have
+     * occurred for those freezes to count at all. `longtask` is process-wide, so without that
+     * corroboration a busy background tab could latch an editor that is typing perfectly happily.
+     */
+    freezeWindowMs: number;
+    /**
+     * How many samples in a full window must individually exceed `slowInputMs`. This is a floor
+     * on how widespread the slowness is, while the median check described on `slowInputMs` is what
+     * stops a couple of outliers qualifying on their own. Both conditions have to hold.
+     */
+    latencySlowSamplesRequired: number;
+    /**
+     * How many keystroke samples the latency criterion is evaluated over. The buffer slides one
+     * sample at a time, dropping the oldest, and the criterion is only checked once it is full.
+     */
+    latencyWindowSize: number;
+    /**
+     * Node count above which the document alone puts the editor into limited mode, compared strictly.
+     * Counted by a full `doc.descendants` walk, which is why `evaluateDocument` is only ever called on
+     * load and on document replacement rather than per transaction.
+     */
+    nodeCountThreshold: number;
+    /**
+     * How many qualifying windows must accumulate before limited mode latches.
+     *
+     * The single most important tunable, because the latch is one-way: a false positive degrades the
+     * editor for the rest of the session. Requiring the evidence to reappear across a
+     * `confirmationGapMs` gap is what distinguishes "this device is struggling" from "something
+     * happened", and stops a large undo, a misbehaving extension or a video call starting from
+     * latching on their own. `1` latches on the first window and skips that protection entirely.
+     */
+    requiredConfirmations: number;
+    /**
+     * The bar for "slow", applied three ways: per sample when counting towards
+     * `latencySlowSamplesRequired`; as the value a full window's *median* must exceed; and to
+     * stamp the most recent slow keystroke, which is what corroborates the freeze criterion.
+     * Every comparison is strict, and the median is used rather than a mean precisely because a
+     * mean is dragged over the bar by one or two outliers.
+     */
+    slowInputMs: number;
+    /**
+     * Grace period, measured from the policy being constructed, during which every signal is
+     * dropped. Editor load is reliably janky and self-resolving, so sampling through it would
+     * latch nearly every session.
+     */
+    warmUpMs: number;
+};
+/** Which criterion closed a qualifying window. */
+export type LatchReason = 
+/** Sustained slow keystrokes. */
+'inputLatency'
+/** Repeated long tasks, corroborated by a slow keystroke. */
+ | 'freeze'
+/** Latched directly by a caller rather than by accumulated evidence — see `latch()`. */
+ | 'forced';
+/**
+ * What the latch was based on, captured at the moment it happened.
+ *
+ * Evidence buffers are cleared on every qualifying window, so the per-window numbers here are
+ * snapshotted before that happens; the `total*` counters are cumulative for the session and are never
+ * cleared, which is what makes them comparable across sessions.
+ */
+export type LatchDetails = {
+    /** Whether the document was already breaching when the runtime criteria latched. */
+    documentAlreadyBreached: boolean;
+    /** Which criterion closed the *first* qualifying window. */
+    firstWindowReason: LatchReason;
+    /** Median of the closing latency window, when `reason` is `inputLatency`. */
+    latencyMedianMs: number | undefined;
+    /**
+     * Elapsed time from the first qualifying window to the latch, so it spans every gap that was
+     * waited out. `0` when a single window latched, and undefined for a forced latch, which has no
+     * qualifying window behind it.
+     */
+    msFromFirstWindow: number | undefined;
+    /** Which criterion closed the window that latched. */
+    reason: LatchReason;
+    /** The `requiredConfirmations` in force for this session, so the bar that was met is known. */
+    requiredConfirmations: number;
+    /** Milliseconds from the policy being constructed to the latch. */
+    timeToLatchMs: number;
+    totalFreezes: number;
+    totalInputSamples: number;
+    totalSlowInputs: number;
+};
+/** Outcome of feeding a signal to the policy. Returned so callers can act on each stage. */
+export type LatchEvaluation = 
+/** Discarded: already latched, still warming up, or suppressed. */
+'ignored'
+/** Counted as evidence, but the bar is not met. */
+ | 'recorded'
+/** A qualifying window closed; still waiting for confirmation. */
+ | 'qualified'
+/** The full bar is met. The caller should latch. */
+ | 'latched';
+export type LatchPolicyOptions = {
+    /** Overrides for individual tunables; anything omitted falls back to the shipped default. */
+    config?: Partial<LatchPolicyConfig>;
+    /** Injectable clock — keeps the policy deterministic under test. */
+    now: () => number;
+};