@docx-editor.dev/core 2.28.0 → 2.30.0

package/dist/diagnostic-hints-2Bke6H_w.d.ts

@@ -0,0 +1,120 @@
+import { b as CollaborationFailureCode } from './failure-NS2lsya4.js';
+
+/**
+ * The public diagnostic vocabulary: stable codes and the buckets sizes and counts are reported
+ * in. It lives in this neutral lane so a headless runtime can name a refusal without the editor
+ * contracts; `contracts/diagnostics.ts` re-exports it for the editor's own types.
+ */
+
+/** Why a document could not be opened. @public */
+type DocumentOpenDiagnosticCode = 'open.unsupported-source' | 'open.zip-corrupt' | 'open.zip-invalid-entry-name' | 'open.zip-entry-limit' | 'open.zip-size-limit' | 'open.zip-ratio-limit' | 'open.xml-malformed' | 'open.xml-dtd-forbidden' | 'open.xml-part-size-limit' | 'open.xml-depth-limit' | 'open.xml-element-limit' | 'open.invalid-limits' | 'open.content-types-invalid' | 'open.missing-main-document' | 'open.relationships-invalid' | 'open.relationship-limit' | 'open.part-limit' | 'open.failed';
+/**
+ * Why `save()` did not return the document: no document was loaded, the document changed while
+ * a pending edit finished, or the save threw.
+ *
+ * @public
+ */
+type DocumentSaveDiagnosticCode = 'save.no-document' | 'save.document-changed' | 'save.failed';
+/** Why an edit, a command or a tracked change was refused. @public */
+type EditDiagnosticCode = 'edit.read-only' | 'edit.protected-content' | 'edit.suggesting-needs-author' | 'edit.review-module-required' | 'edit.tracked-drawing-delete-unsupported' | 'edit.tracked-structure-unsupported' | 'edit.tracked-operation-unsupported' | 'edit.tracking-mode-unsupported' | 'edit.tracking-author-required' | 'edit.tracking-unsupported-host' | 'edit.revision-unsupported' | 'edit.tracking-required' | 'edit.tracked-image-replace-unsupported' | 'edit.picture-selected' | 'edit.cross-structure-join' | 'edit.indivisible-content' | 'edit.field-structure' | 'edit.section-mark' | 'edit.table-structure-unsupported' | 'edit.table-insert-refused' | 'edit.table-of-contents-refused' | 'edit.unsupported-content' | 'edit.operation-unsupported' | 'edit.unsupported-story' | 'edit.unmapped-change' | 'edit.stale-target' | 'edit.invalid-argument' | 'edit.resource-limit' | 'edit.refresh-in-progress' | 'edit.collaboration-not-ready' | 'edit.collaboration-text-limit' | 'edit.internal-invariant' | 'edit.refused';
+/** Why accepting, rejecting or re-authoring a tracked change skipped an item. @public */
+type ReviewDiagnosticCode = 'review.revision-unsupported' | 'review.incomplete-group' | 'review.retained-structure' | 'review.stale-revision';
+/** Why a font did not load. The family name is never reported. @public */
+type FontDiagnosticCode = 'font.shaper-unavailable' | 'font.load-failed' | 'font.missing' | 'font.integrity-mismatch' | 'font.malformed' | 'font.size-limit' | 'font.unsupported-face';
+/**
+ * Why the undo history did not group edits as one step. Informational: nothing was refused.
+ *
+ * @public
+ */
+type HistoryDiagnosticCode = 'history.split' | 'history.possible-ungrouped-gesture' | 'history.possible-fragmented-gesture';
+/**
+ * Why a performance summary needs attention. Informational: nothing was refused.
+ *
+ * @public
+ */
+type PerformanceDiagnosticCode = 'performance.slow-interaction';
+/** Why a custom node's stored payload could not be read. The node name is never reported. @public */
+type CustomNodeDiagnosticCode = 'custom-node.payload-invalid' | 'custom-node.payload-missing';
+/**
+ * Why a collaboration session failed or refused work: `collab.` and the session's own public
+ * {@link CollaborationFailureCode}, such as `collab.authentication-failed`.
+ *
+ * @public
+ */
+type CollaborationDiagnosticCode = `collab.${CollaborationFailureCode}`;
+/** Every public diagnostic code. Codes are stable: a new one is additive, none is renamed. @public */
+type DiagnosticCode = DocumentOpenDiagnosticCode | DocumentSaveDiagnosticCode | EditDiagnosticCode | ReviewDiagnosticCode | FontDiagnosticCode | HistoryDiagnosticCode | CustomNodeDiagnosticCode | PerformanceDiagnosticCode | CollaborationDiagnosticCode;
+/**
+ * A coarse size, in powers of two, so a size cannot single out one document.
+ * `'0-64KiB'` covers everything under 64 KiB; `'512MiB+'` everything above.
+ *
+ * @public
+ */
+type ByteSizeBucket = '0-64KiB' | '64-128KiB' | '128-256KiB' | '256-512KiB' | '512KiB-1MiB' | '1-2MiB' | '2-4MiB' | '4-8MiB' | '8-16MiB' | '16-32MiB' | '32-64MiB' | '64-128MiB' | '128-256MiB' | '256-512MiB' | '512MiB+';
+/** A coarse count: `'0'`, `'1'`, `'2-9'`, `'10-99'`, `'100-999'`, `'1000+'`. @public */
+type CountBucket = '0' | '1' | '2-9' | '10-99' | '100-999' | '1000+';
+/**
+ * Which kind of package part a failure is in, by its role, never by its name: a part's real
+ * name is file data. A name outside the standard layout reports `'other'`.
+ *
+ * @public
+ */
+type DocumentPartKind = 'package' | 'content-types' | 'relationships' | 'main-document' | 'glossary' | 'styles' | 'numbering' | 'settings' | 'web-settings' | 'font-table' | 'theme' | 'header' | 'footer' | 'footnotes' | 'endnotes' | 'comments' | 'people' | 'custom-xml' | 'document-properties' | 'media' | 'embedding' | 'other';
+/**
+ * The class of an unexpected exception, for a failure the engine did not name. The message is
+ * never reported, because it can quote document content.
+ *
+ * @public
+ */
+type DiagnosticErrorName = 'Error' | 'TypeError' | 'RangeError' | 'ReferenceError' | 'SyntaxError' | 'other';
+/** What a tracked-change request was asked to do. @public */
+type ReviewOperation = 'accept' | 'reject' | 'reassign';
+/** The kind of a tracked change, as the review queue lists it. @public */
+type ReviewChangeKind = 'insert' | 'delete' | 'replace' | 'moveFrom' | 'moveTo' | 'format' | 'paragraphMark' | 'structural';
+/**
+ * Which property change a formatting change is, by its OOXML element. A name outside this list
+ * reports `'other'`.
+ *
+ * @public
+ */
+type FormattingChangeKind = 'rPrChange' | 'pPrChange' | 'sectPrChange' | 'tblPrChange' | 'tblPrExChange' | 'tblGridChange' | 'trPrChange' | 'tcPrChange' | 'numberingChange' | 'other';
+/**
+ * Where an exception the engine did not expect was caught: the mount of an open, a later layout
+ * slice of an open, a command, a single review action, or an editing API batch.
+ *
+ * @public
+ */
+type FailureStage = 'open-mount' | 'open-layout' | 'command' | 'review-item' | 'automation' | 'save';
+
+/**
+ * What a diagnostic code means and what to do about it.
+ *
+ * Both strings are constants written for developers. They never contain document content, so
+ * an exporter can send them with the event.
+ *
+ * @public
+ */
+interface DiagnosticExplanation {
+    /** One or two sentences: the cause, then the action. */
+    readonly hint: string;
+    /** The documentation anchor for this code, such as `…/guides/diagnostics#edit-read-only`. */
+    readonly docs: string;
+}
+/**
+ * What a diagnostic code means and what to do about it.
+ *
+ * @example
+ * ```ts
+ * editor.on('diagnostic', (event) => {
+ *   if (event.kind === 'edit.rejected') console.warn(explainDiagnostic(event.code).hint);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function explainDiagnostic(code: DiagnosticCode): DiagnosticExplanation;
+/** Every public code, in declaration order. For coverage tests and catalogs. @public */
+declare function diagnosticCodes(): readonly DiagnosticCode[];
+
+export { diagnosticCodes as l, explainDiagnostic as m };
+export type { ByteSizeBucket as B, CollaborationDiagnosticCode as C, DiagnosticErrorName as D, EditDiagnosticCode as E, FailureStage as F, HistoryDiagnosticCode as H, PerformanceDiagnosticCode as P, ReviewChangeKind as R, DocumentPartKind as a, CountBucket as b, CustomNodeDiagnosticCode as c, DiagnosticCode as d, DiagnosticExplanation as e, DocumentOpenDiagnosticCode as f, DocumentSaveDiagnosticCode as g, FontDiagnosticCode as h, FormattingChangeKind as i, ReviewDiagnosticCode as j, ReviewOperation as k };

package/dist/{document-protection-BAGVGqaP.d.ts → document-protection-8eyMWIJ0.d.ts}

@@ -1,4 +1,4 @@
-import { N as OoxmlNode } from './types-barrel-D3xCgQX6.js';
+import { N as OoxmlNode } from './types-barrel-CA0xB8kH.js';
 
 /** `ST_DocProtect`: the restriction a document asks for. `none` also stands for "no element". */
 type DocumentProtectionEdit = 'none' | 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
@@ -17,4 +17,4 @@ declare const NO_DOCUMENT_PROTECTION: DocumentProtectionState;
 declare function readDocumentProtection(settingsRoot: OoxmlNode | null | undefined): DocumentProtectionState;
 
 export { NO_DOCUMENT_PROTECTION as N, readDocumentProtection as r };
-export type { DocumentProtectionState as D, DocumentProtectionEdit as a };
+export type { DocumentProtectionEdit as D, DocumentProtectionState as a };

package/dist/{editor-Ci7IZGmG.d.ts → editor-DaEJd2so.d.ts}

@@ -1,13 +1,139 @@
-import { d as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './revision-projection-DZ4kKVev.js';
-import { a as ResolvedReviewPane } from './review-pane-D9jm8DcY.js';
-import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, al as SourceCrop, am as DrawingKind, an as ImageWrapTarget, ao as DrawingPositionInput, ap as DrawingLocks, r as ColorValue, x as ExecErrorCode, aq as ParagraphFormatCommand, ar as Watermark, E as ExecResult, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, as as Rect, at as SelectionPin, au as Unsubscribe } from './types-barrel-D3xCgQX6.js';
-import { H as HistoryDiagnostic, V as ViewScope, a as HistoryGroup, b as EditorExecOptions, E as EditorScope } from './editor-scope-OHPwVQ5l.js';
+import { q as ResolvedRevisionMarkup, a as ReviewDisplayMode } from './semantic-records-CjcF26ZL.js';
+import { t as DocAnchor, g as ReviewRevisionKind, c as ReviewCommentItem, b as ReviewRevisionItem, d as ReviewCustomItem, aJ as SourceCrop, Y as DrawingKind, a1 as ImageWrapTarget, _ as DrawingPositionInput, Z as DrawingLocks, r as ColorValue, x as ExecErrorCode, a5 as ParagraphFormatCommand, af as Watermark, E as ExecResult, n as ContentControlFilter, o as DocRange, k as RunFormatting, p as Revision, a7 as Rect, ab as SelectionPin, ae as Unsubscribe } from './types-barrel-CA0xB8kH.js';
+import { H as HistoryDiagnostic, V as ViewScope, b as HistoryGroup, a as EditorExecOptions, E as EditorScope } from './editor-scope-7o9xweiJ.js';
 import { DocEdits, DocQueries, DocQueryResults, ContentControlSummary } from './contracts/document.js';
 import { InteractionOutcome } from './contracts/interaction.js';
-import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-CIC-PooQ.js';
-import { b as ImageResourceState, S as SupportedImageMime } from './image-resources-BN-hUgCn.js';
-import { D as DocumentProtectionState } from './document-protection-BAGVGqaP.js';
+import { a as SemanticSelection, S as SemanticPosition } from './semantic-interaction-Dc3pf3hr.js';
+import { I as ImageResourceState, S as SupportedImageMime } from './image-resources-Bipz8toD.js';
+import { a as DocumentProtectionState } from './document-protection-8eyMWIJ0.js';
 import { C as CollaborationStatus } from './failure-NS2lsya4.js';
+import { C as CollaborationDiagnosticCode, c as CustomNodeDiagnosticCode, D as DiagnosticErrorName, F as FailureStage, B as ByteSizeBucket, b as CountBucket, f as DocumentOpenDiagnosticCode, a as DocumentPartKind, g as DocumentSaveDiagnosticCode, E as EditDiagnosticCode, j as ReviewDiagnosticCode, k as ReviewOperation, R as ReviewChangeKind, i as FormattingChangeKind, h as FontDiagnosticCode, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode } from './diagnostic-hints-2Bke6H_w.js';
+
+/**
+ * When the review pane opens by itself.
+ *
+ * - `'auto'`: the pane opens when a document with review items loads, and when a tracked
+ *   change is made while it is closed, in both cases when the pane has items to list. With
+ *   `revisionsIn: 'balloons'` the pane lists no tracked change and no reply to one, so
+ *   tracked changes and their replies alone do not open it.
+ * - `'manual'`: the pane stays closed until the host or the user opens it. Use it when the
+ *   host shows review items its own way, such as in balloons or margin markers.
+ *
+ * @public
+ */
+type ReviewPaneOpening = 'auto' | 'manual';
+/**
+ * What the open review pane does when its full card column does not fit beside the page at
+ * the page's zoom.
+ *
+ * - `'float'`: the pane shrinks to a strip of markers, and the open card floats over the
+ *   page.
+ * - `'shrinkPage'`: under a fit zoom mode, the page may shrink down to the mode's
+ *   `minZoom` (or 10%) so that the full column fits. The pane changes to the marker strip
+ *   only when the column does not fit at that floor either. A fixed zoom behaves as
+ *   `'float'`.
+ * - `'scroll'`: the page keeps the size it has beside the closed pane's marker strip, and
+ *   the full column stands beside it. The document and the column scroll together: the
+ *   viewport scrolls sideways to reach the cards.
+ *
+ * The setting applies to the review pane only. The navigation pane stays docked at its side
+ * in every mode: it never scrolls with the document, and it takes its room beside the page
+ * exactly as it does with no review pane.
+ *
+ * @public
+ */
+type ReviewPaneOverflow = 'float' | 'shrinkPage' | 'scroll';
+/**
+ * Where tracked changes open.
+ *
+ * - `'pane'`: the review pane lists tracked changes as cards beside the comments.
+ * - `'balloons'`: the pane lists comments only, except comments that reply to a tracked
+ *   change: the change's balloon shows those. A tracked change opens in a balloon at its
+ *   text when the reader clicks it, or when Next Change, Previous Change, or
+ *   `setActiveReviewItem(key, { announce: true })` reaches it.
+ *
+ * @public
+ */
+type RevisionDisplay = 'pane' | 'balloons';
+/**
+ * How a collapsed comment marker looks.
+ *
+ * - `'initials'`: a badge with the thread author's initials in the author's color, a reply
+ *   count, and a check mark when the thread is resolved.
+ * - `'icon'`: the comment icon.
+ *
+ * @public
+ */
+type CommentMarkerStyle = 'initials' | 'icon';
+/**
+ * Review pane settings to change. Every field is optional, and an omitted field keeps its
+ * current value.
+ *
+ * @public
+ */
+interface ReviewPaneOptions {
+    /** Default `'auto'`. */
+    readonly opening?: ReviewPaneOpening;
+    /** Default `'float'`. */
+    readonly overflow?: ReviewPaneOverflow;
+    /** Default `'pane'`. */
+    readonly revisionsIn?: RevisionDisplay;
+    /** Default `'icon'`. */
+    readonly commentMarkers?: CommentMarkerStyle;
+}
+/**
+ * The review pane settings in force, with every field resolved.
+ *
+ * @public
+ */
+interface ResolvedReviewPane {
+    /** When the pane opens by itself. */
+    readonly opening: ReviewPaneOpening;
+    /** What the open pane does when its card column does not fit beside the page. */
+    readonly overflow: ReviewPaneOverflow;
+    /** Where tracked changes open. */
+    readonly revisionsIn: RevisionDisplay;
+    /** How a collapsed comment marker looks. */
+    readonly commentMarkers: CommentMarkerStyle;
+}
+/** The settings an editor starts with when nothing sets them. @public */
+declare const DEFAULT_REVIEW_PANE: ResolvedReviewPane;
+/**
+ * Merge `options` over `base`. Throws a `TypeError` for an unknown field or value, so a
+ * misspelled setting fails loudly instead of being ignored. Returns `base` itself when
+ * nothing changes, so the snapshot keeps its reference.
+ *
+ * @public
+ */
+declare function resolveReviewPane(options: ReviewPaneOptions | undefined, base?: ResolvedReviewPane): ResolvedReviewPane;
+/**
+ * The fields of a review item that decide whether the review pane lists it. A
+ * `ReviewItem` and a review item placement both have them.
+ *
+ * @public
+ */
+interface ReviewPaneItemFields {
+    /** The item kind, as `ReviewItem.kind` gives it. */
+    readonly kind: 'revision' | 'comment' | 'custom';
+    /** For a comment, the tracked change it replies to. */
+    readonly parentRevisionId?: string;
+}
+/**
+ * Whether the review pane lists a card for `item` under `revisionsIn`.
+ *
+ * With `'balloons'`, a balloon at the text shows every tracked change and every comment
+ * that replies to a tracked change, so the pane lists neither. Give the item as an
+ * unfiltered `getReviewItems()` read returns it: a query that excludes revision kinds
+ * removes `parentRevisionId` from replies to the changes it drops.
+ *
+ * The engine applies this rule to every review item when it decides whether the pane opens
+ * by itself or closes after a settings change. A review pane must apply the same rule before
+ * its own filters, such as a hidden kind or a host filter. Those filters can hide every card,
+ * and then the pane that the engine opens is empty.
+ *
+ * @public
+ */
+declare function reviewPaneListsItem(revisionsIn: RevisionDisplay, item: ReviewPaneItemFields): boolean;
 
 /**
  * What a fit mode fits the page to.
@@ -41,6 +167,315 @@ type ZoomMode = {
     readonly maxZoom?: number;
 };
 
+/**
+ * Anonymous diagnostics: why something failed, as stable codes and bucketed numbers.
+ *
+ * A document is user data. Its text, names, part names, relationship targets, author names and
+ * font names never appear in a diagnostic. Every field below is a closed enum, a boolean or a
+ * number, so an event can go to an error tracker or a metrics backend as it is. The internal
+ * rejection reasons stay internal: they map many-to-one onto {@link DiagnosticCode}, which is
+ * the public, versioned vocabulary a host can match on.
+ *
+ * @packageDocumentation
+ */
+
+/** Version of the {@link EditorDiagnostic} shape. Raised only when a field changes meaning. @public */
+declare const DIAGNOSTIC_SCHEMA_VERSION = 1;
+
+/** The bucketed shape of an opened document. @public */
+interface DocumentShape {
+    /** XML parts in the package. */
+    readonly parts: CountBucket;
+    readonly paragraphs: CountBucket;
+    /** Tracked changes and comments, as the review queue lists them. */
+    readonly reviewItems: CountBucket;
+    readonly embeddedFonts: CountBucket;
+}
+/** Fields every diagnostic carries. @public */
+interface DiagnosticBase {
+    /** {@link DIAGNOSTIC_SCHEMA_VERSION} when the event was made. */
+    readonly schemaVersion: number;
+    /**
+     * Random for each editor instance and never stored, so one open failure can be linked to the
+     * edits after it. It identifies no person and no document.
+     */
+    readonly editorSessionId: string;
+    /** Milliseconds since the epoch. */
+    readonly time: number;
+}
+/**
+ * Anonymous detail of a failure, for the engineer who fixes it. Every field is optional and
+ * comes from a closed list: never a part name, an element name, a message, or document text.
+ *
+ * @public
+ */
+interface DiagnosticFailureDetail {
+    /**
+     * The engine's own reason, such as `undeclared-prefix` under `open.xml-malformed`, or
+     * `exception` for an error the engine did not expect. Causes can change between engine
+     * versions: match on `code`, and include the `cause` when you report a problem. See
+     * `diagnosticCauses()` for every value.
+     */
+    readonly cause?: string;
+    /** The class of the exception when `cause` is `exception`. Its message is never reported. */
+    readonly errorName?: DiagnosticErrorName;
+    /** Where the exception was caught, when `cause` is `exception`. */
+    readonly stage?: FailureStage;
+}
+/** A document opened, or failed to open. @public */
+type DocumentOpenDiagnostic = DiagnosticBase & {
+    readonly kind: 'document.open';
+} & ({
+    readonly outcome: 'opened';
+    /** Compressed size of the bytes the editor was given. */
+    readonly sizeBucket: ByteSizeBucket;
+    /** Pages after the first layout. Absent on a headless host that does not paginate. */
+    readonly pagesBucket?: CountBucket;
+    /**
+     * More of the document's shape, in buckets. A telemetry client sends it only when you
+     * ask for the detailed shape: several counts together describe a document more closely.
+     */
+    readonly shape?: DocumentShape;
+    /** Milliseconds from the start of the open to the mounted first layout. */
+    readonly durationMs: number;
+} | (DiagnosticFailureDetail & {
+    readonly outcome: 'rejected';
+    readonly code: DocumentOpenDiagnosticCode;
+    /** Compressed size of the bytes, absent when the source was not bytes at all. */
+    readonly sizeBucket?: ByteSizeBucket;
+    /** The role of the part that failed, such as `'header'`. Never its name. */
+    readonly part?: DocumentPartKind;
+}));
+/**
+ * A `save()` call returned the document, or failed. Reported for each call, by the editor that
+ * saved. A save the host does afterwards, such as an upload, is the host's to measure.
+ *
+ * @public
+ */
+type DocumentSaveDiagnostic = DiagnosticBase & {
+    readonly kind: 'document.save';
+} & ({
+    readonly outcome: 'saved';
+    /** Size of the saved bytes. */
+    readonly sizeBucket: ByteSizeBucket;
+    /** Milliseconds from the `save()` call to the bytes, pending edits included. */
+    readonly durationMs: number;
+} | (DiagnosticFailureDetail & {
+    readonly outcome: 'rejected';
+    readonly code: DocumentSaveDiagnosticCode;
+    /** Milliseconds from the `save()` call to the failure. */
+    readonly durationMs: number;
+}));
+/**
+ * What an editor did over a window of use or over its whole session. Counts and milliseconds
+ * only: no key, position, command argument or text.
+ *
+ * @public
+ */
+interface SessionActivity {
+    /**
+     * For `active`, milliseconds from the window's first activity to the summary. For `end`,
+     * milliseconds from the editor's creation to its end, idle time included.
+     */
+    readonly durationMs: number;
+    /**
+     * Milliseconds of use: the time between key presses, pointer presses and edits that are at
+     * most 30 seconds apart. A longer pause counts as idle.
+     */
+    readonly activeMs: number;
+    /**
+     * Edits from typing, the clipboard, drag and drop, keyboard undo, and other input that changed
+     * the document. Each committed change counts once: typing commits about one change per
+     * character, and characters typed faster than the editor paints commit together.
+     */
+    readonly inputEdits: number;
+    /** Editor commands, from `exec(...)` or the toolbar, that changed the document. */
+    readonly commandEdits: number;
+    /** Editing API batches that changed the document. */
+    readonly automationEdits: number;
+}
+/**
+ * The lifecycle and activity of one editor instance, without any content.
+ *
+ * - `start`: the editor was created.
+ * - `active`: a summary of one window of use. Sent after a minute of activity, when the page is
+ *   hidden, and before `end`, if anything happened since the last summary. An idle editor sends
+ *   none, so `active` is not a heartbeat.
+ * - `end`: the editor was destroyed, or the page closed. Carries totals for the whole session.
+ *
+ * Edits count changes this editor committed. Refused edits are in `edit.rejected`, and edits
+ * that collaborators made are not counted. Sum `active` summaries or read `end` totals, not
+ * both: the totals include every summary.
+ *
+ * @public
+ */
+type SessionDiagnostic = DiagnosticBase & {
+    readonly kind: 'session';
+} & ({
+    readonly phase: 'start';
+} | (SessionActivity & {
+    readonly phase: 'active' | 'end';
+}));
+/** Where a refused edit came from. @public */
+type EditRejectionOrigin = 'command' | 'input' | 'automation';
+/** An edit, a command or a tracked change was refused. @public */
+interface EditRejectedDiagnostic extends DiagnosticBase, DiagnosticFailureDetail {
+    readonly kind: 'edit.rejected';
+    readonly code: EditDiagnosticCode;
+    /**
+     * `'command'` for `exec(...)`, `'input'` for typing, clipboard, drag and pointer edits, and
+     * `'automation'` for a batch from the editing API.
+     */
+    readonly origin: EditRejectionOrigin;
+    /** True when the editor was suggesting (tracking changes) at the time. */
+    readonly tracked: boolean;
+    /** The command type for `origin: 'command'`, such as `'insertTable'`. */
+    readonly command?: EditorCommand['type'];
+}
+/**
+ * An accept, reject or re-author request skipped one or more tracked changes. One event for each
+ * code and kind of change in the request.
+ *
+ * @public
+ */
+interface ReviewSkippedDiagnostic extends DiagnosticBase {
+    readonly kind: 'review.skipped';
+    readonly code: ReviewDiagnosticCode;
+    /** How many items were skipped for this code and kind in the one request. */
+    readonly count: number;
+    /** What the request asked: accept, reject, or attribute to another author. */
+    readonly operation?: ReviewOperation;
+    /** The kind of the skipped changes, absent when the change no longer exists. */
+    readonly changeKind?: ReviewChangeKind;
+    /** For `changeKind: 'format'`, which property change it is. */
+    readonly formattingKind?: FormattingChangeKind;
+    /** The role of the part the changes are in, such as `'footnotes'`. Never its name. */
+    readonly part?: DocumentPartKind;
+    /**
+     * For `review.revision-unsupported`, the engine condition that refused the change, such as
+     * `unaddressed` (no `w:id` or author) or `unrecorded-properties`. See `diagnosticCauses()`.
+     */
+    readonly cause?: string;
+}
+/** A font failed to load. The editor kept working with a substitute. @public */
+interface FontFailedDiagnostic extends DiagnosticBase {
+    readonly kind: 'font.failed';
+    readonly code: FontDiagnosticCode;
+}
+/**
+ * A collaboration session changed status: it joined, disconnected, failed, or healed.
+ *
+ * @public
+ */
+interface CollaborationStatusDiagnostic extends DiagnosticBase {
+    readonly kind: 'collab.status';
+    readonly status: CollaborationStatus;
+    /** The status before this change; `'none'` for the first status the editor saw. */
+    readonly previous: CollaborationStatus | 'none';
+    /** Why the session holds `status`, when something is wrong. */
+    readonly code?: CollaborationDiagnosticCode;
+    /** True when the session will heal on its own; wait instead of rejoining. */
+    readonly recovering: boolean;
+    /**
+     * Milliseconds from the editor attaching the session to its first `ready`. Present only on
+     * that change, and only when the editor saw the wait: a session that was already ready when
+     * the editor attached, as `useHocuspocusCollaboration` makes it, reports none.
+     */
+    readonly connectMs?: number;
+}
+/** The undo history did not group edits as the gesture intended. Informational. @public */
+interface HistoryDiagnosticEvent extends DiagnosticBase {
+    readonly kind: 'history';
+    readonly code: HistoryDiagnosticCode;
+}
+/** A custom node's stored payload could not be read. The node and its data are not named. @public */
+interface CustomNodeDiagnosticEvent extends DiagnosticBase {
+    readonly kind: 'custom-node';
+    readonly code: CustomNodeDiagnosticCode;
+}
+/** The number of people in the collaboration room changed. @public */
+interface CollaborationParticipantsDiagnostic extends DiagnosticBase {
+    readonly kind: 'collab.participants';
+    /** People present, this editor included. A person with two tabs counts twice. */
+    readonly count: number;
+}
+/**
+ * Timings of one kind over a performance window. Every value is in milliseconds, rounded to
+ * whole milliseconds.
+ *
+ * @public
+ */
+interface TimingSummary {
+    /** Timings measured in the window. */
+    readonly count: number;
+    /** Median. Exact up to 2048 timings; above that, from a uniform sample of 2048. */
+    readonly p50Ms: number;
+    /** 95th percentile, from the same sample as the median. */
+    readonly p95Ms: number;
+    /** The slowest timing, always exact. */
+    readonly maxMs: number;
+    /**
+     * Timings per band, always exact. Eight counts: up to 16, 33, 50, 100, 200, 500, and 1000
+     * ms, then over 1000 ms. A metrics backend builds a histogram from these.
+     */
+    readonly bands: readonly number[];
+}
+/**
+ * How the editor performed while it was used: one summary per window, never one event per key
+ * press. Sent after a minute of use, when the page is hidden, and when the editor is destroyed,
+ * if anything was measured since the last summary.
+ *
+ * @public
+ */
+interface PerformanceDiagnostic extends DiagnosticBase {
+    readonly kind: 'performance';
+    /**
+     * Present when the summary needs attention: `performance.slow-interaction` when at least 20
+     * presses were timed and more than one in 20 took over 200 ms.
+     */
+    readonly code?: PerformanceDiagnosticCode;
+    /**
+     * Milliseconds from the window's first timing to the summary, one minute or less. Idle time
+     * inside the window counts, so this is not active editing time. Use the `count` of
+     * `interaction` to measure activity.
+     */
+    readonly windowMs: number;
+    /** Pages in the document at the last paint. */
+    readonly pagesBucket?: CountBucket;
+    /**
+     * Key presses and pointer presses on the pages, from the browser event to the next frame on
+     * screen: the delay a person feels. Presses queued behind slow work count with their full
+     * delay. Presses of modifier keys alone, and presses while the page is hidden, are not timed.
+     */
+    readonly interaction?: TimingSummary;
+    /**
+     * Engine layout passes that the person causes, by an edit or a view change such as zoom.
+     * Each pass includes its main-thread work in the background, and the work of a pass that a
+     * newer edit replaced. Layouts that loading causes are not here: the opening layout, which
+     * `document.open` reports as `durationMs`, and layouts after fonts or images arrive.
+     */
+    readonly layout?: TimingSummary;
+    /** Engine paints of the pages. */
+    readonly paint?: TimingSummary;
+}
+/**
+ * One anonymous diagnostic. Switch on `kind` to narrow `code`.
+ *
+ * @example
+ * ```ts
+ * editor.on('diagnostic', (event) => {
+ *   if (event.kind === 'edit.rejected') {
+ *     console.warn(event.code, explainDiagnostic(event.code).hint);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+type EditorDiagnostic = DocumentOpenDiagnostic | EditRejectedDiagnostic | ReviewSkippedDiagnostic | FontFailedDiagnostic | HistoryDiagnosticEvent | CustomNodeDiagnosticEvent | CollaborationStatusDiagnostic | CollaborationParticipantsDiagnostic | PerformanceDiagnostic | DocumentSaveDiagnostic | SessionDiagnostic;
+/** The `kind` of every {@link EditorDiagnostic}. @public */
+type EditorDiagnosticKind = EditorDiagnostic['kind'];
+
 /**
  * What `editor.on(...)` can be subscribed to, and what each handler receives.
  *
@@ -57,6 +492,22 @@ interface EditorEvents {
     selectionChange: (snapshot: EditorSnapshot) => void;
     error: (error: EditorError) => void;
     historyDiagnostic: (diagnostic: HistoryDiagnostic) => void;
+    /**
+     * An anonymous diagnostic: a document opened or failed to open, an edit or a tracked change
+     * was refused, a font failed. Carries stable codes and bucketed numbers, never document
+     * content, so a handler may send it to an error tracker as it is.
+     *
+     * A document passed at construction opens before a host can subscribe. To see that open,
+     * register a module with `onDiagnostic` instead.
+     *
+     * @example
+     * ```ts
+     * editor.on('diagnostic', (event) => {
+     *   if (event.kind === 'edit.rejected') console.warn(explainDiagnostic(event.code).hint);
+     * });
+     * ```
+     */
+    diagnostic: (event: EditorDiagnostic) => void;
     /**
      * An explicit request landed on a review item, and its card or balloon should open.
      *
@@ -2444,5 +2895,5 @@ interface EditorError extends Error {
     readonly code?: string;
 }
 
-export { EditorFontError as E, cropPercentFromCropPermille as s, cropPercentFromPermille as t, cropPercentFromSourceCrop as u, cropPermilleFromCropPercent as v, cropPermilleFromPercent as w, sourceCropFromCropPercent as x, validateImageCropPercent as y };
-export type { EditorHighlights as $, AnchorHighlightOptions as A, TableBorderEdgeTarget as B, CanResult as C, DocumentSource as D, FontFaceRequest as F, TableBorderSpec as G, HighlightRange as H, ImageContext as I, TableBorderStyle as J, TableContext as K, AuthoredNoteNumbering as L, DocumentChange as M, DocumentEditingMode as N, DocumentHandle as O, EditorAnchorNavigation as P, EditorCommandShape as Q, ReviewItemHit as R, ScrollToAnchorOptions as S, TextMatch as T, EditorCommands as U, EditorError as V, EditorEvents as W, EditorFontErrorCode as X, EditorFormatPainterCommands as Y, ZoomMode as Z, EditorHeaderFooterCommands as _, FontConfiguration as a, EditorNoteCommands as a0, EditorPosition as a1, EditorQueries as a2, EditorQuery as a3, EditorQueryResults as a4, EditorReviewHits as a5, EditorSelection as a6, FormatPainterLevel as a7, FormatPainterMode as a8, FurnitureVariant as a9, ZoomFitTarget as aA, HeaderFooterSlotArgs as aa, HeaderFooterState as ab, HyperlinkInfo as ac, NoteKind as ad, NotePropertiesSide as ae, NotePropertiesState as af, PageSetup as ag, ResolveReviewChangesOptions as ah, ResolvedNoteNumbering as ai, ReviewActivationOptions as aj, ReviewChangesAttribution as ak, ReviewCommentPlacement as al, ReviewCustomPlacement as am, ReviewItemPlacement as an, ReviewItemPlacementBase as ao, ReviewItemQuery as ap, ReviewItemRevealEvent as aq, ReviewItemRevealSource as ar, ReviewRevisionPlacement as as, SetReviewChangesAuthorOptions as at, TableBorderTarget as au, TableCellVerticalAlignment as av, TableColumnDividerResizeTarget as aw, TableColumnOccurrenceTarget as ax, TableRightEdgeResizeTarget as ay, TableRowOccurrenceTarget as az, FontSource as b, FontSourceSubstitution as c, EditorSnapshot as d, EditorCommand as e, ClearAnchorHighlightOptions as f, ScrollPlacement as g, AnchorHighlightAnimation as h, Editor as i, HighlightResult as j, HighlightOptions as k, HighlightHit as l, HighlightRect as m, ImageCropPercent as n, ImageCropPermille as o, SelectedImageState as p, TrackedChangeFilterMode as q, TrackedChangePredicate as r, FormatPainterSurfaceState as z };
+export { DIAGNOSTIC_SCHEMA_VERSION as D, resolveReviewPane as a$, DEFAULT_REVIEW_PANE as aQ, cropPercentFromCropPermille as aW, cropPercentFromPermille as aX, cropPercentFromSourceCrop as aY, cropPermilleFromCropPercent as aZ, cropPermilleFromPercent as a_, reviewPaneListsItem as b0, sourceCropFromCropPercent as b1, validateImageCropPercent as b2, EditorFontError as z };
+export type { HeaderFooterState as $, AnchorHighlightAnimation as A, EditorFontErrorCode as B, CanResult as C, EditorDiagnostic as E, EditorFormatPainterCommands as F, EditorHeaderFooterCommands as G, EditorHighlights as H, EditorNoteCommands as I, EditorPosition as J, EditorQueries as K, EditorQuery as L, EditorQueryResults as M, EditorReviewHits as N, EditorSelection as O, EditorSnapshot as P, FontConfiguration as Q, ReviewPaneOptions as R, FontFaceRequest as S, FontFailedDiagnostic as T, FontSource as U, FontSourceSubstitution as V, FormatPainterLevel as W, FormatPainterMode as X, FormatPainterSurfaceState as Y, FurnitureVariant as Z, HeaderFooterSlotArgs as _, EditorDiagnosticKind as a, HighlightHit as a0, HighlightOptions as a1, HighlightRange as a2, HighlightRect as a3, HighlightResult as a4, HistoryDiagnosticEvent as a5, HyperlinkInfo as a6, ImageContext as a7, ImageCropPercent as a8, NoteKind as a9, TableBorderStyle as aA, TableBorderTarget as aB, TableCellVerticalAlignment as aC, TableColumnDividerResizeTarget as aD, TableColumnOccurrenceTarget as aE, TableContext as aF, TableRightEdgeResizeTarget as aG, TableRowOccurrenceTarget as aH, TextMatch as aI, TimingSummary as aJ, TrackedChangeFilterMode as aK, TrackedChangePredicate as aL, ZoomFitTarget as aM, ZoomMode as aN, ReviewPaneOverflow as aO, CommentMarkerStyle as aP, ImageCropPermille as aR, ResolvedReviewPane as aS, ReviewPaneItemFields as aT, ReviewPaneOpening as aU, RevisionDisplay as aV, NotePropertiesSide as aa, NotePropertiesState as ab, PageSetup as ac, PerformanceDiagnostic as ad, ResolveReviewChangesOptions as ae, ResolvedNoteNumbering as af, ReviewActivationOptions as ag, ReviewChangesAttribution as ah, ReviewCommentPlacement as ai, ReviewCustomPlacement as aj, ReviewItemHit as ak, ReviewItemPlacement as al, ReviewItemPlacementBase as am, ReviewItemQuery as an, ReviewItemRevealEvent as ao, ReviewItemRevealSource as ap, ReviewRevisionPlacement as aq, ReviewSkippedDiagnostic as ar, ScrollPlacement as as, ScrollToAnchorOptions as at, SelectedImageState as au, SessionActivity as av, SessionDiagnostic as aw, SetReviewChangesAuthorOptions as ax, TableBorderEdgeTarget as ay, TableBorderSpec as az, EditorCommand as b, AnchorHighlightOptions as c, AuthoredNoteNumbering as d, ClearAnchorHighlightOptions as e, CollaborationParticipantsDiagnostic as f, CollaborationStatusDiagnostic as g, CustomNodeDiagnosticEvent as h, DiagnosticBase as i, DiagnosticFailureDetail as j, DocumentChange as k, DocumentEditingMode as l, DocumentHandle as m, DocumentOpenDiagnostic as n, DocumentSaveDiagnostic as o, DocumentShape as p, DocumentSource as q, EditRejectedDiagnostic as r, EditRejectionOrigin as s, Editor as t, EditorAnchorNavigation as u, EditorCommandShape as v, EditorCommands as w, EditorError as x, EditorEvents as y };

package/dist/{editor-scope-OHPwVQ5l.d.ts → editor-scope-7o9xweiJ.d.ts}

@@ -81,4 +81,4 @@ interface HistoryDiagnostic {
     readonly reason: string;
 }
 
-export type { EditorScope as E, HistoryDiagnostic as H, ViewScope as V, HistoryGroup as a, EditorExecOptions as b, HistoryGroupOutcome as c };
+export type { EditorScope as E, HistoryDiagnostic as H, ViewScope as V, EditorExecOptions as a, HistoryGroup as b, HistoryGroupOutcome as c };