@docx-editor.dev/core 2.27.0 → 2.29.0

package/dist/collaboration/replication.cjs

@@ -1 +1 @@
-'use strict';var chunkGVUOWHTO_cjs=require('../chunk-GVUOWHTO.cjs'),chunk4KZ6L5YF_cjs=require('../chunk-4KZ6L5YF.cjs');Object.defineProperty(exports,"createCollaborationDocumentPort",{enumerable:true,get:function(){return chunkGVUOWHTO_cjs.b}});Object.defineProperty(exports,"historyGroupOfJournal",{enumerable:true,get:function(){return chunk4KZ6L5YF_cjs.Ba}});Object.defineProperty(exports,"registerUndoHistoryPosition",{enumerable:true,get:function(){return chunk4KZ6L5YF_cjs.ok}});Object.defineProperty(exports,"reportHistoryGroup",{enumerable:true,get:function(){return chunk4KZ6L5YF_cjs.nk}});
+'use strict';var chunkUHHYFIDT_cjs=require('../chunk-UHHYFIDT.cjs'),chunkOSFOJTHU_cjs=require('../chunk-OSFOJTHU.cjs');Object.defineProperty(exports,"createCollaborationDocumentPort",{enumerable:true,get:function(){return chunkUHHYFIDT_cjs.b}});Object.defineProperty(exports,"mapOffsetAcrossText",{enumerable:true,get:function(){return chunkUHHYFIDT_cjs.c}});Object.defineProperty(exports,"historyGroupOfJournal",{enumerable:true,get:function(){return chunkOSFOJTHU_cjs.Ja}});Object.defineProperty(exports,"registerUndoHistoryPosition",{enumerable:true,get:function(){return chunkOSFOJTHU_cjs.jl}});Object.defineProperty(exports,"reportHistoryGroup",{enumerable:true,get:function(){return chunkOSFOJTHU_cjs.il}});

package/dist/collaboration/replication.d.ts

@@ -1,8 +1,24 @@
-import { d as HistoryGroup, T as TreePackageStore, e as TreeModelChange } from '../tree-package-fragment-DYZIk1rY.js';
-export { r as reportHistoryGroup } from '../tree-package-fragment-DYZIk1rY.js';
-import { Z as OoxmlElement, Q as OoxmlPackage } from '../types-barrel-BFKR8Pzp.js';
-import '../image-resources-BDFxcu7W.js';
-import '../editor-scope-OHPwVQ5l.js';
+/**
+ * `@docx-editor.dev/core/collaboration/replication` — the seam a replication implementation
+ * binds to, not the surface a host consumes.
+ *
+ * Everything here exists for the layer BETWEEN a CRDT and the canonical tree: the document
+ * port an adapter writes through, the primitive journal it reads, and the descriptors that
+ * journal is made of. A host that renders presence and reads a status needs none of it, which
+ * is why it lives behind its own subpath — autocomplete on
+ * `@docx-editor.dev/core/collaboration` should not offer `putXmlPart` and `spliceChildren` to
+ * somebody wiring up an avatar stack.
+ *
+ * Reach for this when you are writing a provider. `@docx-editor.dev/pro` is one.
+ *
+ * @packageDocumentation
+ * @public
+ */
+import { d as HistoryGroup, T as TreePackageStore, e as TreeModelChange } from '../tree-package-store-CovjNARF.js';
+export { r as reportHistoryGroup } from '../tree-package-store-CovjNARF.js';
+import { ak as OoxmlElement, Q as OoxmlPackage } from '../types-barrel-DuC5QBNC.js';
+import '../image-resources-tXLQShoC.js';
+import '../editor-scope-7o9xweiJ.js';
 
 /** Attribute name as the journal addresses it. Prefix is authored fidelity, not identity. @public */
 interface CanonicalAttributeName {
@@ -119,6 +135,21 @@ interface CreateCollaborationDocumentPortOptions {
 /** Create the narrow collaboration view over one canonical package store. @public */
 declare function createCollaborationDocumentPort(store: TreePackageStore, options: CreateCollaborationDocumentPortOptions): CollaborationDocumentPort;
 
+/**
+ * Offsets carried across changes to a paragraph's text, for the local caret and the carets
+ * peers show.
+ */
+/**
+ * An offset carried across one change to a paragraph's text.
+ *
+ * The local caret and the carets peers show both stay next to the same character this way,
+ * whatever a peer typed or deleted around it, even when one remote update changed text on
+ * both sides of the offset.
+ *
+ * @public
+ */
+declare function mapOffsetAcrossText(offset: number, before: string, after: string): number;
+
 /** An editor-local view action must stay between the same document undo entries. */
 interface UndoHistoryPosition {
     current(): object | null;
@@ -185,6 +216,11 @@ interface CollaborationDocumentPort {
     readonly documentId: string;
     paragraphs(): readonly CollaborationParagraph[];
     paragraphByNodeId(nodeId: string): CollaborationParagraph | null;
+    /**
+     * The model text of the paragraph with this node id in any story, or null when the editor
+     * shows none. A lookup by node id, whatever the paragraph's `w14:paraId`. Optional.
+     */
+    paragraphTextOf?(nodeId: string): string | null;
     /**
      * Resolve a stable `w14:paraId` in any story this replica holds.
      *
@@ -230,5 +266,5 @@ interface CollaborationDocumentPort {
     binaryPart(storageKey: string): Uint8Array | null;
 }
 
-export { HistoryGroup, createCollaborationDocumentPort, historyGroupOfJournal, registerUndoHistoryPosition };
+export { HistoryGroup, createCollaborationDocumentPort, historyGroupOfJournal, mapOffsetAcrossText, registerUndoHistoryPosition };
 export type { CanonicalAttributeName, CanonicalBinaryDescriptor, CanonicalElementNodeDescriptor, CanonicalNodeDescriptor, CanonicalPrimitiveEffect, CanonicalPrimitiveJournal, CanonicalRelationshipRecord, CanonicalTextNodeDescriptor, CollaborationApplyResult, CollaborationDocumentPort, CollaborationMutation, CollaborationParagraph, CollaborationParagraphTextUpdate, CreateCollaborationDocumentPortOptions };

package/dist/collaboration/replication.js

@@ -1 +1 @@
-export{b as createCollaborationDocumentPort}from'../chunk-DNXVNQEO.js';export{Ba as historyGroupOfJournal,ok as registerUndoHistoryPosition,nk as reportHistoryGroup}from'../chunk-UMRSBLO7.js';
+export{b as createCollaborationDocumentPort,c as mapOffsetAcrossText}from'../chunk-OMCG63ZF.js';export{Ja as historyGroupOfJournal,jl as registerUndoHistoryPosition,il as reportHistoryGroup}from'../chunk-YQ5G6LC7.js';

package/dist/collaboration.cjs

@@ -1 +1 @@
-'use strict';var chunkBTQKU64Q_cjs=require('./chunk-BTQKU64Q.cjs');var u={"already-initialized":true,"authentication-failed":true,"baseline-digest-mismatch":true,"baseline-too-large":true,"blob-digest-mismatch":true,"blob-read":true,"blob-store-full":true,"blob-too-large":true,"collaboration-format-mismatch":true,"collaboration-session-destroyed":true,"collaboration-session-not-attached":true,"collaboration-session-not-ready":true,"collaboration-text-limit":true,"concurrent-seed":true,"document-id-mismatch":true,"duplicate-paragraph-id":true,"experimental-collaboration-body-text-only":true,"experimental-collaboration-existing-paragraphs-only":true,"experimental-collaboration-text-only":true,"experimental-collaboration-untracked-text-only":true,"immutable-baseline-changed":true,"immutable-metadata-changed":true,"initialization-aborted":true,"initialization-timeout":true,"invalid-baseline":true,"invalid-blob-descriptor":true,"invalid-bound":true,"invalid-document-id":true,"invalid-identity":true,"invalid-identity-color":true,"invalid-logical-id":true,"invalid-relationships":true,"invalid-saved-room":true,"invalid-session-id":true,"invalid-shared-metadata":true,"invalid-string":true,"local-mirror-failed":true,"materialize-dropped-content":true,"missing-blob":true,"missing-local-blob":true,"missing-root":true,"no-main-document-part":true,"not-initialized":true,"paragraph-set-mismatch":true,"port-already-attached":true,"protocol-version-mismatch":true,"prototype-key":true,"remote-apply-failed":true,"saved-room-unavailable":true,"schema-version-mismatch":true,"shared-schema-invalid":true,"text-too-long":true,"too-many-attributes":true,"too-many-children":true,"too-many-nodes":true,"too-many-parts":true,"too-many-relationships":true,transport:true,"transport-disconnected":true,"tree-too-deep":true,"unknown-logical-id":true,"unknown-paragraph-id":true,"unsafe-part-name":true,"unsupported-root-key":true};function c(t){return Object.hasOwn(u,t)}function b(t,o){return t===o?true:!t||!o?false:t.code===o.code&&t.detail===o.detail}function p(t,o){return Object.freeze(o!==void 0&&o.length>0?{code:t,detail:o}:{code:t})}function m(t="initializing"){let o=t,e,r,n=Object.freeze({status:o,reason:e,lastFailure:r});return {status:()=>o,snapshot:()=>n,set(i,l,s){let a=l===void 0?void 0:p(l,s);return o===i&&b(e,a)?false:(o=i,e=a,i==="error"&&a&&(r=a),n=Object.freeze({status:o,reason:e,lastFailure:r}),true)}}}Object.defineProperty(exports,"safeParticipantColor",{enumerable:true,get:function(){return chunkBTQKU64Q_cjs.a}});exports.createCollaborationStatusTracker=m;exports.isCollaborationFailureCode=c;
+'use strict';var chunkBTQKU64Q_cjs=require('./chunk-BTQKU64Q.cjs');var C={"already-initialized":true,"authentication-failed":true,"baseline-digest-mismatch":true,"baseline-too-large":true,"blob-digest-mismatch":true,"blob-read":true,"blob-store-full":true,"blob-too-large":true,"collaboration-format-mismatch":true,"collaboration-session-destroyed":true,"collaboration-session-not-attached":true,"collaboration-session-not-ready":true,"collaboration-text-limit":true,"concurrent-seed":true,"document-id-mismatch":true,"duplicate-paragraph-id":true,"experimental-collaboration-body-text-only":true,"experimental-collaboration-existing-paragraphs-only":true,"experimental-collaboration-text-only":true,"experimental-collaboration-untracked-text-only":true,"immutable-baseline-changed":true,"immutable-metadata-changed":true,"initialization-aborted":true,"initialization-timeout":true,"invalid-baseline":true,"invalid-blob-descriptor":true,"invalid-bound":true,"invalid-document-id":true,"invalid-identity":true,"invalid-identity-color":true,"invalid-logical-id":true,"invalid-relationships":true,"invalid-saved-room":true,"invalid-session-id":true,"invalid-shared-metadata":true,"invalid-string":true,"local-mirror-failed":true,"materialize-dropped-content":true,"missing-blob":true,"missing-local-blob":true,"missing-root":true,"no-main-document-part":true,"not-initialized":true,"paragraph-set-mismatch":true,"port-already-attached":true,"protocol-version-mismatch":true,"prototype-key":true,"remote-apply-failed":true,"room-generation-changed":true,"saved-room-unavailable":true,"schema-version-mismatch":true,"shared-schema-invalid":true,"text-too-long":true,"too-many-attributes":true,"too-many-children":true,"too-many-nodes":true,"too-many-parts":true,"too-many-relationships":true,transport:true,"transport-disconnected":true,"tree-too-deep":true,"unknown-logical-id":true,"unknown-paragraph-id":true,"unsafe-part-name":true,"unsupported-root-key":true};function g(e){return Object.hasOwn(C,e)}function f(e,o){return e===o?true:!e||!o?false:e.code===o.code&&e.detail===o.detail}function h(e,o){return Object.freeze(o!==void 0&&o.length>0?{code:e,detail:o}:{code:e})}function S(e="initializing"){let o=e,a,l,s=0,r=false,i=false,d=Object.freeze({status:o,reason:a,lastFailure:l,failureCount:s,recovering:r,waiting:i}),u=()=>{d=Object.freeze({status:o,reason:a,lastFailure:l,failureCount:s,recovering:r,waiting:i});};return {status:()=>o,snapshot:()=>d,set(t,c,p,m=false){let n=c===void 0?void 0:h(c,p),b=t==="error"&&m;return o===t&&f(a,n)&&r===b?false:(o=t,a=n,r=b,t==="error"&&n&&(l=n,s+=1),u(),true)},setWaiting(t){return i===t?false:(i=t,u(),true)}}}Object.defineProperty(exports,"safeParticipantColor",{enumerable:true,get:function(){return chunkBTQKU64Q_cjs.a}});exports.createCollaborationStatusTracker=S;exports.isCollaborationFailureCode=g;

package/dist/collaboration.d.ts

@@ -1,10 +1,19 @@
-import { S as StoryScope } from './tree-package-fragment-DYZIk1rY.js';
-import { W as TreeDocOp } from './types-barrel-BFKR8Pzp.js';
+/**
+ * `@docx-editor.dev/core/collaboration` — provider-neutral collaboration contracts.
+ *
+ * This lane names the attachment between the canonical tree and an optional replication
+ * implementation. It performs no networking and imports no CRDT.
+ *
+ * @packageDocumentation
+ * @public
+ */
+import { S as StoryScope } from './tree-package-store-CovjNARF.js';
+import { ag as TreeDocOp } from './types-barrel-DuC5QBNC.js';
 import { CollaborationDocumentPort } from './collaboration/replication.js';
-import { C as CollaborationStatus, a as CollaborationStatusSnapshot, b as CollaborationFailureCode } from './failure-BIPVQbRm.js';
-export { c as CollaborationFailure, d as createCollaborationStatusTracker, i as isCollaborationFailureCode } from './failure-BIPVQbRm.js';
-import './image-resources-BDFxcu7W.js';
-import './editor-scope-OHPwVQ5l.js';
+import { C as CollaborationStatus, a as CollaborationStatusSnapshot, b as CollaborationFailureCode } from './failure-NS2lsya4.js';
+export { c as CollaborationFailure, d as createCollaborationStatusTracker, i as isCollaborationFailureCode } from './failure-NS2lsya4.js';
+import './image-resources-tXLQShoC.js';
+import './editor-scope-7o9xweiJ.js';
 
 /**
  * A peer's presence color is attacker-controlled: it arrives over awareness from whoever is in
@@ -36,13 +45,18 @@ declare function safeParticipantColor(value: string | undefined): string | undef
 
 /** Human or automation identity attached to authored collaboration transactions. @public */
 interface CollaborationIdentity {
+    /** Stable author id, 1 to 256 characters after trimming. Recorded on authored changes. */
     readonly actorId: string;
+    /** Display name, 1 to 256 characters after trimming. */
     readonly name: string;
+    /** Presence color, at most 64 characters. An unsafe CSS color falls back to the accent. */
     readonly color?: string;
+    /** `agent` for automation. Defaults to `human`. */
     readonly role?: 'human' | 'agent';
 }
 /** One validated identity visible through ephemeral collaboration presence. @public */
 interface CollaborationParticipant extends CollaborationIdentity {
+    /** True for this replica's own participant. */
     readonly isLocal: boolean;
 }
 /**
@@ -54,7 +68,9 @@ interface CollaborationParticipant extends CollaborationIdentity {
  * @public
  */
 interface CollaborationSelectionAddress {
+    /** The stable `w14:paraId` of the paragraph. */
     readonly paragraphId: string;
+    /** A UTF-16 offset in the paragraph's text. */
     readonly offset: number;
 }
 /**
@@ -75,8 +91,11 @@ type CollaborationSelectionKind = 'cells';
  * @public
  */
 interface CollaborationRemoteSelectionAddress {
+    /** The stable `w14:paraId` of the paragraph. */
     readonly paragraphId: string;
+    /** The paragraph's node id in this replica's editor tree. */
     readonly nodeId: string;
+    /** A UTF-16 offset in the paragraph's text. */
     readonly offset: number;
 }
 /**
@@ -87,11 +106,17 @@ interface CollaborationRemoteSelectionAddress {
  * @public
  */
 interface CollaborationRemoteSelection {
+    /** The participant's `actorId`. */
     readonly actorId: string;
+    /** The participant's display name. */
     readonly name: string;
+    /** The participant's presence color, when it published a safe one. */
     readonly color?: string;
+    /** Where the selection starts. */
     readonly anchor: CollaborationRemoteSelectionAddress;
+    /** Where the selection ends: the remote caret. */
     readonly head: CollaborationRemoteSelectionAddress;
+    /** `cells` for a table cell rectangle; absent for a character range. */
     readonly kind?: CollaborationSelectionKind;
 }
 /**
@@ -102,10 +127,42 @@ interface CollaborationRemoteSelection {
  * @public
  */
 interface CollaborationLocalSelection {
+    /** Where the selection starts. */
     readonly anchor: CollaborationSelectionAddress;
+    /** Where the selection ends: the caret. */
     readonly head: CollaborationSelectionAddress;
+    /** `cells` for a table cell rectangle; absent for a character range. */
     readonly kind?: CollaborationSelectionKind;
 }
+/**
+ * Where a collaboration session carried the local selection across the last remote change.
+ *
+ * The editor uses `to` only while its selection still equals `from`: a selection the user
+ * moved since is the user's. @public
+ */
+interface CollaborationSelectionMove {
+    /** The selection the session carried, as the editor last published it. */
+    readonly from: CollaborationEditorSelection;
+    /** Where it stands now: beside the same characters, wherever they show. */
+    readonly to: CollaborationEditorSelection;
+}
+/** A selection in this replica's editor. @public */
+interface CollaborationEditorSelection {
+    /** Where the selection starts: it stays put when the selection extends. */
+    readonly anchor: CollaborationEditorPosition;
+    /** Where the selection ends: the caret. */
+    readonly head: CollaborationEditorPosition;
+}
+/**
+ * A position in this replica's editor tree. Unlike a stable paragraph id, which a remote
+ * change can rename on one replica, a node id names one paragraph of this editor. @public
+ */
+interface CollaborationEditorPosition {
+    /** The node id of the paragraph in this replica's editor tree. */
+    readonly nodeId: string;
+    /** A UTF-16 offset in the paragraph's text. */
+    readonly offset: number;
+}
 /**
  * Optional replication session attached to an editor or headless automation host.
  *
@@ -115,10 +172,13 @@ interface CollaborationLocalSelection {
  * @public
  */
 interface EditorCollaborationSession {
+    /** The room's document id. An attached port must carry the same id. */
     readonly documentId: string;
     /** Unique identity for this attachment lifetime. It prevents operation ID reuse after reconnect. */
     readonly sessionId: string;
+    /** The validated local identity. */
     readonly identity: CollaborationIdentity;
+    /** Current lifecycle state. */
     status(): CollaborationStatus;
     /**
      * Cached status, current reason, and last failure.
@@ -127,7 +187,12 @@ interface EditorCollaborationSession {
      * recovered error still reads {@link CollaborationStatusSnapshot.lastFailure}.
      */
     statusSnapshot(): CollaborationStatusSnapshot;
+    /** Call `listener` on each status or reason change. Returns the unsubscribe function. */
     subscribeStatus(listener: (status: CollaborationStatus, reason?: CollaborationFailureCode, detail?: string) => void): () => void;
+    /**
+     * Attach the editor's document port and start replicating. Returns the detach function.
+     * A second, different port moves the session to `error` with `port-already-attached`.
+     */
     attach(port: CollaborationDocumentPort): () => void;
     /**
      * Whether an editor has attached its document port to this replica.
@@ -138,15 +203,41 @@ interface EditorCollaborationSession {
      * production build discards; this is the same fact as a value a host can render.
      */
     readonly attached: boolean;
+    /**
+     * Check whether `ops` may commit now. Returns `null` to admit them, or the refusal code.
+     * Call it before every store transaction a custom port commits.
+     */
     gateOperations(ops: readonly TreeDocOp[], scope: StoryScope): CollaborationFailureCode | null;
+    /** Whether the shared undo history holds a local step to undo. */
     canUndo(): boolean;
+    /** Whether the shared undo history holds a local step to redo. */
     canRedo(): boolean;
+    /** Undo this participant's last step; others' edits stay. Returns false when refused. */
     undo(): boolean;
+    /** Redo this participant's last undone step. Returns false when refused. */
     redo(): boolean;
+    /**
+     * The selection the last `undo` or `redo` restored: the one its author had before the
+     * undone change. Null when the step recorded none. Optional; a session without it leaves
+     * the editor to place the caret at the change.
+     */
+    historySelection?(): CollaborationLocalSelection | null;
+    /**
+     * Where the last remote change carried the local selection, on the shared characters
+     * beside its endpoints, and the selection it was carried from, both in the editor's
+     * paragraph node ids. Null when the session could not carry it. Optional; without it the
+     * editor maps the selection by text.
+     */
+    remoteSelectionMove?(): CollaborationSelectionMove | null;
+    /** Publish the local selection through presence. `null` clears it. */
     setLocalSelection(selection: CollaborationLocalSelection | null): void;
+    /** Participants in presence, this replica included. Capped at 256. */
     participants(): readonly CollaborationParticipant[];
+    /** Call `listener` when the participant list changes. Returns the unsubscribe function. */
     subscribeParticipants(listener: (participants: readonly CollaborationParticipant[]) => void): () => void;
+    /** Other participants' selections, resolved into this replica's addresses. */
     remoteSelections(): readonly CollaborationRemoteSelection[];
+    /** Call `listener` when a remote selection changes. Returns the unsubscribe function. */
     subscribeRemoteSelections(listener: (selections: readonly CollaborationRemoteSelection[]) => void): () => void;
     /**
      * Publish queued local journals to shared state.
@@ -155,6 +246,7 @@ interface EditorCollaborationSession {
      * so a queued journal is never dropped.
      */
     flushPendingJournals(): void;
+    /** Stop replicating and release listeners. The status becomes `destroyed`. */
     destroy(): void;
 }
 /**
@@ -174,4 +266,4 @@ interface CollaborationModuleContribution {
 }
 
 export { CollaborationFailureCode, CollaborationStatus, CollaborationStatusSnapshot, safeParticipantColor };
-export type { CollaborationIdentity, CollaborationLocalSelection, CollaborationModuleContribution, CollaborationParticipant, CollaborationRemoteSelection, CollaborationRemoteSelectionAddress, CollaborationSelectionAddress, CollaborationSelectionKind, EditorCollaborationSession };
+export type { CollaborationEditorPosition, CollaborationEditorSelection, CollaborationIdentity, CollaborationLocalSelection, CollaborationModuleContribution, CollaborationParticipant, CollaborationRemoteSelection, CollaborationRemoteSelectionAddress, CollaborationSelectionAddress, CollaborationSelectionKind, CollaborationSelectionMove, EditorCollaborationSession };

package/dist/collaboration.js

@@ -1 +1 @@
-export{a as safeParticipantColor}from'./chunk-6JIJOZDW.js';var u={"already-initialized":true,"authentication-failed":true,"baseline-digest-mismatch":true,"baseline-too-large":true,"blob-digest-mismatch":true,"blob-read":true,"blob-store-full":true,"blob-too-large":true,"collaboration-format-mismatch":true,"collaboration-session-destroyed":true,"collaboration-session-not-attached":true,"collaboration-session-not-ready":true,"collaboration-text-limit":true,"concurrent-seed":true,"document-id-mismatch":true,"duplicate-paragraph-id":true,"experimental-collaboration-body-text-only":true,"experimental-collaboration-existing-paragraphs-only":true,"experimental-collaboration-text-only":true,"experimental-collaboration-untracked-text-only":true,"immutable-baseline-changed":true,"immutable-metadata-changed":true,"initialization-aborted":true,"initialization-timeout":true,"invalid-baseline":true,"invalid-blob-descriptor":true,"invalid-bound":true,"invalid-document-id":true,"invalid-identity":true,"invalid-identity-color":true,"invalid-logical-id":true,"invalid-relationships":true,"invalid-saved-room":true,"invalid-session-id":true,"invalid-shared-metadata":true,"invalid-string":true,"local-mirror-failed":true,"materialize-dropped-content":true,"missing-blob":true,"missing-local-blob":true,"missing-root":true,"no-main-document-part":true,"not-initialized":true,"paragraph-set-mismatch":true,"port-already-attached":true,"protocol-version-mismatch":true,"prototype-key":true,"remote-apply-failed":true,"saved-room-unavailable":true,"schema-version-mismatch":true,"shared-schema-invalid":true,"text-too-long":true,"too-many-attributes":true,"too-many-children":true,"too-many-nodes":true,"too-many-parts":true,"too-many-relationships":true,transport:true,"transport-disconnected":true,"tree-too-deep":true,"unknown-logical-id":true,"unknown-paragraph-id":true,"unsafe-part-name":true,"unsupported-root-key":true};function c(t){return Object.hasOwn(u,t)}function b(t,o){return t===o?true:!t||!o?false:t.code===o.code&&t.detail===o.detail}function p(t,o){return Object.freeze(o!==void 0&&o.length>0?{code:t,detail:o}:{code:t})}function m(t="initializing"){let o=t,e,r,n=Object.freeze({status:o,reason:e,lastFailure:r});return {status:()=>o,snapshot:()=>n,set(i,l,s){let a=l===void 0?void 0:p(l,s);return o===i&&b(e,a)?false:(o=i,e=a,i==="error"&&a&&(r=a),n=Object.freeze({status:o,reason:e,lastFailure:r}),true)}}}export{m as createCollaborationStatusTracker,c as isCollaborationFailureCode};
+export{a as safeParticipantColor}from'./chunk-6JIJOZDW.js';var C={"already-initialized":true,"authentication-failed":true,"baseline-digest-mismatch":true,"baseline-too-large":true,"blob-digest-mismatch":true,"blob-read":true,"blob-store-full":true,"blob-too-large":true,"collaboration-format-mismatch":true,"collaboration-session-destroyed":true,"collaboration-session-not-attached":true,"collaboration-session-not-ready":true,"collaboration-text-limit":true,"concurrent-seed":true,"document-id-mismatch":true,"duplicate-paragraph-id":true,"experimental-collaboration-body-text-only":true,"experimental-collaboration-existing-paragraphs-only":true,"experimental-collaboration-text-only":true,"experimental-collaboration-untracked-text-only":true,"immutable-baseline-changed":true,"immutable-metadata-changed":true,"initialization-aborted":true,"initialization-timeout":true,"invalid-baseline":true,"invalid-blob-descriptor":true,"invalid-bound":true,"invalid-document-id":true,"invalid-identity":true,"invalid-identity-color":true,"invalid-logical-id":true,"invalid-relationships":true,"invalid-saved-room":true,"invalid-session-id":true,"invalid-shared-metadata":true,"invalid-string":true,"local-mirror-failed":true,"materialize-dropped-content":true,"missing-blob":true,"missing-local-blob":true,"missing-root":true,"no-main-document-part":true,"not-initialized":true,"paragraph-set-mismatch":true,"port-already-attached":true,"protocol-version-mismatch":true,"prototype-key":true,"remote-apply-failed":true,"room-generation-changed":true,"saved-room-unavailable":true,"schema-version-mismatch":true,"shared-schema-invalid":true,"text-too-long":true,"too-many-attributes":true,"too-many-children":true,"too-many-nodes":true,"too-many-parts":true,"too-many-relationships":true,transport:true,"transport-disconnected":true,"tree-too-deep":true,"unknown-logical-id":true,"unknown-paragraph-id":true,"unsafe-part-name":true,"unsupported-root-key":true};function g(e){return Object.hasOwn(C,e)}function f(e,o){return e===o?true:!e||!o?false:e.code===o.code&&e.detail===o.detail}function h(e,o){return Object.freeze(o!==void 0&&o.length>0?{code:e,detail:o}:{code:e})}function S(e="initializing"){let o=e,a,l,s=0,r=false,i=false,d=Object.freeze({status:o,reason:a,lastFailure:l,failureCount:s,recovering:r,waiting:i}),u=()=>{d=Object.freeze({status:o,reason:a,lastFailure:l,failureCount:s,recovering:r,waiting:i});};return {status:()=>o,snapshot:()=>d,set(t,c,p,m=false){let n=c===void 0?void 0:h(c,p),b=t==="error"&&m;return o===t&&f(a,n)&&r===b?false:(o=t,a=n,r=b,t==="error"&&n&&(l=n,s+=1),u(),true)},setWaiting(t){return i===t?false:(i=t,u(),true)}}}export{S as createCollaborationStatusTracker,g as isCollaborationFailureCode};

package/dist/contracts/document.d.ts

@@ -1,6 +1,21 @@
-import { D as DocxDocument, E as ExecResult, i as ContentControlType, j as DocTarget, k as RunFormatting, l as Extent, I as InsertableContentControlType, m as ContainerRef, n as ContentControlFilter, o as DocRange, p as Revision, q as DocComment, S as StyleDefinitions } from '../types-barrel-BFKR8Pzp.js';
-export { B as Block, r as ColorValue, s as ContentControl, t as DocAnchor, u as DocAnchorRange, v as DocLocation, w as DocumentBody, x as ExecErrorCode, H as HeaderFooterSet, y as IndentFormatting, P as Paragraph, z as ParagraphFlags, A as ParagraphTabStop, F as RevisionType, G as Section, J as SectionProperties, K as StyleDefinition, T as Table, L as Theme, M as ThemeColorScheme } from '../types-barrel-BFKR8Pzp.js';
-import '../editor-scope-OHPwVQ5l.js';
+/**
+ * `@docx-editor.dev/core/contracts/document` — the document-level edit and query vocabulary.
+ *
+ * The subset that means something without a live editor: what an automation host or an LLM tool
+ * can ask for and change.
+ *
+ * A CONTRACT module, not a barrel. `contracts/editor` builds the `Editor` command and query
+ * surfaces on top of these, so they cannot live in the package root: the root re-exports
+ * runtime from `../editor`, and a contract importing the root would invert the dependency —
+ * safe today only because that import is type-only, and one accidental value import away from
+ * pulling the painted engine into a server bundle.
+ *
+ * @packageDocumentation
+ * @public
+ */
+import { D as DocxDocument, E as ExecResult, i as ContentControlType, j as DocTarget, k as RunFormatting, l as Extent, I as InsertableContentControlType, m as ContainerRef, n as ContentControlFilter, o as DocRange, p as Revision, q as DocComment, S as StyleDefinitions } from '../types-barrel-DuC5QBNC.js';
+export { B as Block, r as ColorValue, s as ContentControl, t as DocAnchor, u as DocAnchorRange, v as DocLocation, w as DocumentBody, x as ExecErrorCode, H as HeaderFooterSet, y as IndentFormatting, P as Paragraph, z as ParagraphFlags, A as ParagraphTabStop, F as RevisionType, G as Section, J as SectionProperties, K as StyleDefinition, T as Table, L as Theme, M as ThemeColorScheme } from '../types-barrel-DuC5QBNC.js';
+import '../editor-scope-7o9xweiJ.js';
 
 /**
  * `@docx-editor.dev/core/contracts/document` — the document-level edit and query vocabulary.

package/dist/contracts/editor.d.ts

@@ -1,12 +1,21 @@
-import '../revision-projection-CSNFudZY.js';
-export { g as AnchorHighlightAnimation, A as AnchorHighlightOptions, K as AuthoredNoteNumbering, C as CanResult, f as ClearAnchorHighlightOptions, L as DocumentChange, M as DocumentEditingMode, N as DocumentHandle, D as DocumentSource, h as Editor, O as EditorAnchorNavigation, e as EditorCommand, P as EditorCommandShape, Q as EditorCommands, R as EditorError, U as EditorEvents, E as EditorFontError, V as EditorFontErrorCode, W as EditorFormatPainterCommands, X as EditorHeaderFooterCommands, Y as EditorHighlights, _ as EditorNoteCommands, $ as EditorPosition, a0 as EditorQueries, a1 as EditorQuery, a2 as EditorQueryResults, a3 as EditorSelection, d as EditorSnapshot, a as FontConfiguration, F as FontFaceRequest, b as FontSource, c as FontSourceSubstitution, a4 as FormatPainterLevel, a5 as FormatPainterMode, y as FormatPainterSurfaceState, a6 as FurnitureVariant, a7 as HeaderFooterSlotArgs, a8 as HeaderFooterState, k as HighlightHit, j as HighlightOptions, H as HighlightRange, l as HighlightRect, i as HighlightResult, a9 as HyperlinkInfo, I as ImageContext, m as ImageCropPercent, aa as NoteKind, ab as NotePropertiesSide, ac as NotePropertiesState, ad as PageSetup, ae as ResolveReviewChangesOptions, af as ResolvedNoteNumbering, ag as ReviewActivationOptions, ah as ReviewCommentPlacement, ai as ReviewCustomPlacement, aj as ReviewItemPlacement, ak as ReviewItemPlacementBase, al as ReviewItemQuery, am as ReviewRevisionPlacement, S as ScrollToAnchorOptions, o as SelectedImageState, z as TableBorderEdgeTarget, B as TableBorderSpec, G as TableBorderStyle, an as TableBorderTarget, ao as TableCellVerticalAlignment, ap as TableColumnDividerResizeTarget, aq as TableColumnOccurrenceTarget, J as TableContext, ar as TableRightEdgeResizeTarget, as as TableRowOccurrenceTarget, T as TextMatch, p as TrackedChangeFilterMode, q as TrackedChangePredicate, at as ZoomFitTarget, Z as ZoomMode } from '../editor-B3OBYNrF.js';
-export { B as Block, r as ColorValue, C as CommentRecord, m as ContainerRef, s as ContentControl, n as ContentControlFilter, i as ContentControlType, t as DocAnchor, u as DocAnchorRange, q as DocComment, v as DocLocation, o as DocRange, j as DocTarget, w as DocumentBody, D as DocxDocument, ai as DocxDocumentJSON, aj as DrawingHorizontalReferenceFrame, a9 as DrawingKind, ac as DrawingLocks, ab as DrawingPositionInput, ak as DrawingVerticalReferenceFrame, x as ExecErrorCode, E as ExecResult, l as Extent, al as FontDefinition, H as HeaderFooterSet, aa as ImageWrapTarget, y as IndentFormatting, I as InsertableContentControlType, am as NumberingRef, an as PageMargins, P as Paragraph, ao as ParagraphDisagreements, z as ParagraphFlags, ad as ParagraphFormatCommand, A as ParagraphTabStop, ap as Point, af as Rect, c as ReviewCommentItem, d as ReviewCustomItem, a as ReviewItem, e as ReviewPosition, f as ReviewRange, b as ReviewRevisionItem, g as ReviewRevisionKind, p as Revision, h as RevisionAddress, a3 as RevisionBatchResult, F as RevisionType, aq as Run, k as RunFormatting, G as Section, J as SectionProperties, ag as SelectionPin, K as StyleDefinition, S as StyleDefinitions, T as Table, ar as TableCell, as as TableRow, L as Theme, M as ThemeColorScheme, ah as Unsubscribe, ae as Watermark } from '../types-barrel-BFKR8Pzp.js';
+/**
+ * `@docx-editor.dev/core/contracts/editor` — the `Editor` contract adapters are written against.
+ *
+ * Commands go through `can` before `exec`; queries answer against the live, laid-out document.
+ * Type-only declarations let adapters name the surface without importing the engine.
+ *
+ * @packageDocumentation
+ * @public
+ */
+export { a as ReviewDisplayMode } from '../semantic-records-DQmumPgL.js';
+export { A as AnchorHighlightAnimation, c as AnchorHighlightOptions, d as AuthoredNoteNumbering, C as CanResult, e as ClearAnchorHighlightOptions, f as CollaborationParticipantsDiagnostic, g as CollaborationStatusDiagnostic, h as CustomNodeDiagnosticEvent, D as DIAGNOSTIC_SCHEMA_VERSION, i as DiagnosticBase, j as DiagnosticFailureDetail, k as DocumentChange, l as DocumentEditingMode, m as DocumentHandle, n as DocumentOpenDiagnostic, o as DocumentShape, p as DocumentSource, q as EditRejectedDiagnostic, r as EditRejectionOrigin, s as Editor, t as EditorAnchorNavigation, b as EditorCommand, u as EditorCommandShape, v as EditorCommands, E as EditorDiagnostic, a as EditorDiagnosticKind, w as EditorError, x as EditorEvents, y as EditorFontError, z as EditorFontErrorCode, B as EditorFormatPainterCommands, F as EditorHeaderFooterCommands, G as EditorHighlights, H as EditorNoteCommands, I as EditorPosition, J as EditorQueries, K as EditorQuery, L as EditorQueryResults, M as EditorReviewHits, N as EditorSelection, O as EditorSnapshot, P as FontConfiguration, Q as FontFaceRequest, S as FontFailedDiagnostic, T as FontSource, U as FontSourceSubstitution, V as FormatPainterLevel, W as FormatPainterMode, X as FormatPainterSurfaceState, Y as FurnitureVariant, Z as HeaderFooterSlotArgs, _ as HeaderFooterState, $ as HighlightHit, a0 as HighlightOptions, a1 as HighlightRange, a2 as HighlightRect, a3 as HighlightResult, a4 as HistoryDiagnosticEvent, a5 as HyperlinkInfo, a6 as ImageContext, a7 as ImageCropPercent, a8 as NoteKind, a9 as NotePropertiesSide, aa as NotePropertiesState, ab as PageSetup, ac as PerformanceDiagnostic, ad as ResolveReviewChangesOptions, ae as ResolvedNoteNumbering, af as ReviewActivationOptions, ag as ReviewChangesAttribution, ah as ReviewCommentPlacement, ai as ReviewCustomPlacement, aj as ReviewItemHit, ak as ReviewItemPlacement, al as ReviewItemPlacementBase, am as ReviewItemQuery, an as ReviewItemRevealEvent, ao as ReviewItemRevealSource, ap as ReviewRevisionPlacement, aq as ReviewSkippedDiagnostic, ar as ScrollPlacement, as as ScrollToAnchorOptions, at as SelectedImageState, au as SetReviewChangesAuthorOptions, av as TableBorderEdgeTarget, aw as TableBorderSpec, ax as TableBorderStyle, ay as TableBorderTarget, az as TableCellVerticalAlignment, aA as TableColumnDividerResizeTarget, aB as TableColumnOccurrenceTarget, aC as TableContext, aD as TableRightEdgeResizeTarget, aE as TableRowOccurrenceTarget, aF as TextMatch, aG as TimingSummary, aH as TrackedChangeFilterMode, aI as TrackedChangePredicate, aJ as ZoomFitTarget, aK as ZoomMode } from '../editor-CZQZmTIU.js';
+export { B as Block, r as ColorValue, C as CommentRecord, m as ContainerRef, s as ContentControl, n as ContentControlFilter, i as ContentControlType, t as DocAnchor, u as DocAnchorRange, q as DocComment, v as DocLocation, o as DocRange, j as DocTarget, w as DocumentBody, D as DocxDocument, W as DocxDocumentJSON, X as DrawingHorizontalReferenceFrame, Y as DrawingKind, Z as DrawingLocks, _ as DrawingPositionInput, $ as DrawingVerticalReferenceFrame, x as ExecErrorCode, E as ExecResult, l as Extent, a0 as FontDefinition, H as HeaderFooterSet, a1 as ImageWrapTarget, y as IndentFormatting, I as InsertableContentControlType, a2 as NumberingRef, a3 as PageMargins, P as Paragraph, a4 as ParagraphDisagreements, z as ParagraphFlags, a5 as ParagraphFormatCommand, A as ParagraphTabStop, a6 as Point, a7 as Rect, c as ReviewCommentItem, d as ReviewCustomItem, a as ReviewItem, e as ReviewPosition, f as ReviewRange, b as ReviewRevisionItem, g as ReviewRevisionKind, p as Revision, h as RevisionAddress, a8 as RevisionAuthorResult, a9 as RevisionBatchResult, F as RevisionType, aa as Run, k as RunFormatting, G as Section, J as SectionProperties, ab as SelectionPin, K as StyleDefinition, S as StyleDefinitions, T as Table, ac as TableCell, ad as TableRow, L as Theme, M as ThemeColorScheme, ae as Unsubscribe, af as Watermark } from '../types-barrel-DuC5QBNC.js';
 export { ContentControlSummary, DocEdits, DocQueries, DocQueryResults, ParagraphSummary } from './document.js';
-export { b as EditorExecOptions, E as EditorScope, H as HistoryDiagnostic, a as HistoryGroup, c as HistoryGroupOutcome, V as ViewScope } from '../editor-scope-OHPwVQ5l.js';
+export { a as EditorExecOptions, E as EditorScope, H as HistoryDiagnostic, b as HistoryGroup, c as HistoryGroupOutcome, V as ViewScope } from '../editor-scope-7o9xweiJ.js';
 export { InteractionAffinity, InteractionOutcome, InteractionOutcomeCode, SemanticIdentity, SemanticTarget } from './interaction.js';
-export { S as SemanticPosition, a as SemanticSelection } from '../semantic-interaction-G0bjmmmk.js';
-export { b as ImageResourceState, P as PreservedImageMime, R as RenderableImageMime, S as SupportedImageMime, V as ValidatedImageBytesHandle, c as VectorImageMime } from '../image-resources-BDFxcu7W.js';
-import '../document-protection-9zpIHWTE.js';
-import '../failure-BIPVQbRm.js';
-import '../semantic-records-B9OolWGN.js';
-import '../omml-equation-DuczgG5o.js';
+export { S as SemanticPosition, a as SemanticSelection } from '../semantic-interaction-kR_QB845.js';
+export { I as ImageResourceState, P as PreservedImageMime, R as RenderableImageMime, S as SupportedImageMime, V as ValidatedImageBytesHandle, a as VectorImageMime } from '../image-resources-tXLQShoC.js';
+import '../document-protection-CUb55pl_.js';
+import '../failure-NS2lsya4.js';
+export { B as ByteSizeBucket, C as CollaborationDiagnosticCode, b as CountBucket, c as CustomNodeDiagnosticCode, d as DiagnosticCode, D as DiagnosticErrorName, e as DiagnosticExplanation, f as DocumentOpenDiagnosticCode, a as DocumentPartKind, E as EditDiagnosticCode, F as FailureStage, g as FontDiagnosticCode, h as FormattingChangeKind, H as HistoryDiagnosticCode, P as PerformanceDiagnosticCode, R as ReviewChangeKind, i as ReviewDiagnosticCode, j as ReviewOperation } from '../diagnostic-hints-BeVjfNOv.js';
+import '../omml-equation-BUbU0utM.js';

package/dist/contracts/interaction.d.ts

@@ -1,5 +1,34 @@
-import { V as ViewScope } from '../editor-scope-OHPwVQ5l.js';
-export { E as EditorScope } from '../editor-scope-OHPwVQ5l.js';
+/**
+ * `@docx-editor.dev/core/contracts/interaction` — semantic addressing and interaction outcomes.
+ *
+ * Semantic identities and targets: the vocabulary a caller uses to say WHICH text it means,
+ * independent of layout, DOM or any editing engine's positions. Plus the outcome type an
+ * interaction attempt answers with. That is the whole module.
+ *
+ * It used to be 599 lines. An "interaction frame" lived here — a revision-tagged projection
+ * of display, page geometry, caret and selection overlays, focus, composition and
+ * accessibility, plus a typed pointer-intent dispatch protocol and a render IR of glyph
+ * runs — and every one of those declarations was consumed by exactly nothing. They
+ * described an architecture the engine does not use: the paginated surface owns pointer
+ * interaction internally and paints through `Editor.attach`, so no frame was ever published
+ * and no intent ever dispatched.
+ * THREE of them (`CaretGeometry`, `HitTestOptions`, `ShapedCluster`) also collided by name
+ * with the REAL, differently-shaped types in `layout/`, so the published contract carried a
+ * second definition of a live concept and `import { ShapedCluster }` meant different things
+ * depending on which module you reached for.
+ * `InteractionFrameId` and a frame-tagged `SemanticSelection` outlived that cut. Both were
+ * the same mistake: the id was a placeholder nothing ever minted (`focus` returned a literal
+ * `{ value: 0 }`), and the selection could not be CONSTRUCTED without one, which made it a
+ * fourth name-collision with the real `SemanticSelection` in `layout/` that a caller could
+ * never actually satisfy.
+ *
+ * CONTRACT ONLY — declarations, not an implementation.
+ *
+ * @packageDocumentation
+ * @public
+ */
+import { V as ViewScope } from '../editor-scope-7o9xweiJ.js';
+export { E as EditorScope } from '../editor-scope-7o9xweiJ.js';
 
 /**
  * `@docx-editor.dev/core/contracts/interaction` — semantic addressing and interaction outcomes.

package/dist/contracts/modules.cjs

@@ -1 +1 @@
-'use strict';var chunkNBCVVZOM_cjs=require('../chunk-NBCVVZOM.cjs');Object.defineProperty(exports,"resolveEditorModules",{enumerable:true,get:function(){return chunkNBCVVZOM_cjs.a}});
+'use strict';var chunkV3N4SOAK_cjs=require('../chunk-V3N4SOAK.cjs');Object.defineProperty(exports,"resolveEditorModules",{enumerable:true,get:function(){return chunkV3N4SOAK_cjs.a}});

package/dist/contracts/modules.d.ts

@@ -1,13 +1,39 @@
-import { R as RevisionMarkupDialogSession, a as ReviewDisplayMode } from '../revision-projection-CSNFudZY.js';
-export { b as RevisionDisplayMode } from '../revision-projection-CSNFudZY.js';
-import { R as ReviewModelInput, a as ReviewItem, O as OoxmlPart, b as ReviewRevisionItem } from '../types-barrel-BFKR8Pzp.js';
-export { C as CommentRecord, c as ReviewCommentItem, d as ReviewCustomItem, e as ReviewPosition, f as ReviewRange, g as ReviewRevisionKind, h as RevisionAddress } from '../types-barrel-BFKR8Pzp.js';
+/**
+ * `@docx-editor.dev/core/contracts/modules` — the `EditorModule` seam.
+ *
+ * How a paid or optional capability contributes to the engine without the free tier importing
+ * it: the review module and custom nodes both arrive through here, and their absence leaves the
+ * corresponding chrome disabled with the engine's own reason.
+ *
+ * NOT a plugin system. The shape is closed: every contribution point is named
+ * here, core iterates registered modules at its existing dispatch points, and
+ * core never imports a capability package. A capability absent from this file
+ * is not extendable from outside — deliberately, so the one-pipeline principle
+ * survives the packaging boundary.
+ * The free engine behaves identically with an empty registry: documents
+ * round-trip losslessly, revisions render in their final-state projection, and
+ * the review chrome slots stay disabled with the engine's own reason.
+ *
+ * @packageDocumentation
+ * @public
+ */
+import { R as RevisionMarkupDialogSession, a as ReviewDisplayMode } from '../semantic-records-DQmumPgL.js';
+export { b as RevisionDisplayMode } from '../semantic-records-DQmumPgL.js';
+import { R as ReviewPaneOptions, E as EditorDiagnostic, a as EditorDiagnosticKind } from '../editor-CZQZmTIU.js';
+import { R as ReviewModelInput, a as ReviewItem, O as OoxmlPart, b as ReviewRevisionItem } from '../types-barrel-DuC5QBNC.js';
+export { C as CommentRecord, c as ReviewCommentItem, d as ReviewCustomItem, e as ReviewPosition, f as ReviewRange, g as ReviewRevisionKind, h as RevisionAddress } from '../types-barrel-DuC5QBNC.js';
 import { CollaborationModuleContribution } from '../collaboration.js';
-import '../editor-scope-OHPwVQ5l.js';
-import '../tree-package-fragment-DYZIk1rY.js';
-import '../image-resources-BDFxcu7W.js';
+import '../image-resources-tXLQShoC.js';
+import '../omml-equation-BUbU0utM.js';
+import '../editor-scope-7o9xweiJ.js';
+import './document.js';
+import './interaction.js';
+import '../semantic-interaction-kR_QB845.js';
+import '../document-protection-CUb55pl_.js';
+import '../failure-NS2lsya4.js';
+import '../diagnostic-hints-BeVjfNOv.js';
+import '../tree-package-store-CovjNARF.js';
 import '../collaboration/replication.js';
-import '../failure-BIPVQbRm.js';
 
 /**
  * Derives the review queue — every pending revision decision and comment
@@ -44,6 +70,10 @@ interface ReviewModuleContribution {
      * The module enables the listed review projections.
      */
     readonly displayModes: readonly ReviewDisplayMode[];
+    /**
+     * The review pane settings the editor starts with. `setReviewPaneOptions` changes them later.
+     */
+    readonly pane?: ReviewPaneOptions;
     /** The review queue derivation. */
     readonly collectReviewItems: CollectReviewItems;
     /**
@@ -97,6 +127,20 @@ interface EditorModule {
      * package that raised it.
      */
     readonly onCustomNodeDiagnostic?: (diagnostic: unknown) => void;
+    /**
+     * Told about every anonymous diagnostic of this editor, from its first open on.
+     *
+     * The same events as `editor.on('diagnostic')`, but registered before the editor exists, so
+     * a document passed at construction is observed too. A listener that throws is ignored: an
+     * observer must never break the editor it observes.
+     */
+    readonly onDiagnostic?: (event: EditorDiagnostic) => void;
+    /**
+     * Whether `onDiagnostic` wants events of `kind` now. Absent, it wants every kind. The editor
+     * asks before work that only a diagnostic needs, such as timing key presses for
+     * `performance`, and skips that work when no listener wants it. Read often: keep it cheap.
+     */
+    readonly wantsDiagnostic?: (kind: EditorDiagnosticKind) => boolean;
 }
 /**
  * The resolved registry the editor instance holds: at most one review
@@ -111,6 +155,10 @@ interface EditorModuleRegistry {
     readonly customNodePayloadNamespaces: readonly string[];
     /** Every registered diagnostic listener, in registration order. */
     readonly customNodeDiagnostics: readonly ((diagnostic: unknown) => void)[];
+    /** Every registered `onDiagnostic` listener, in registration order. */
+    readonly diagnosticListeners: readonly ((event: EditorDiagnostic) => void)[];
+    /** Whether any module with `onDiagnostic` wants events of `kind` now. */
+    readonly wantsDiagnostic: (kind: EditorDiagnosticKind) => boolean;
 }
 /** Resolve construction-time modules into the registry the instance dispatches over. */
 declare function resolveEditorModules(modules: readonly EditorModule[] | undefined): EditorModuleRegistry;

package/dist/contracts/modules.js

@@ -1 +1 @@
-export{a as resolveEditorModules}from'../chunk-O5INAWZQ.js';
+export{a as resolveEditorModules}from'../chunk-4HENIAFG.js';

package/dist/contracts/types.d.ts

@@ -1,2 +1,11 @@
-export { B as Block, r as ColorValue, m as ContainerRef, s as ContentControl, n as ContentControlFilter, i as ContentControlType, t as DocAnchor, u as DocAnchorRange, q as DocComment, v as DocLocation, o as DocRange, j as DocTarget, w as DocumentBody, D as DocxDocument, ai as DocxDocumentJSON, x as ExecErrorCode, E as ExecResult, l as Extent, al as FontDefinition, H as HeaderFooterSet, y as IndentFormatting, I as InsertableContentControlType, am as NumberingRef, an as PageMargins, P as Paragraph, ao as ParagraphDisagreements, z as ParagraphFlags, ad as ParagraphFormatCommand, A as ParagraphTabStop, ap as Point, af as Rect, p as Revision, F as RevisionType, aq as Run, k as RunFormatting, G as Section, J as SectionProperties, ag as SelectionPin, K as StyleDefinition, S as StyleDefinitions, T as Table, ar as TableCell, as as TableRow, L as Theme, M as ThemeColorScheme, ah as Unsubscribe, ae as Watermark } from '../types-barrel-BFKR8Pzp.js';
-import '../editor-scope-OHPwVQ5l.js';
+/**
+ * `@docx-editor.dev/core/contracts/types` — the shared type vocabulary. Zero runtime.
+ *
+ * Addressing (`DocAnchor`, `DocTarget`), the document model, and the geometry primitives every
+ * other contract is written in terms of.
+ *
+ * @packageDocumentation
+ * @public
+ */
+export { B as Block, r as ColorValue, m as ContainerRef, s as ContentControl, n as ContentControlFilter, i as ContentControlType, t as DocAnchor, u as DocAnchorRange, q as DocComment, v as DocLocation, o as DocRange, j as DocTarget, w as DocumentBody, D as DocxDocument, W as DocxDocumentJSON, x as ExecErrorCode, E as ExecResult, l as Extent, a0 as FontDefinition, H as HeaderFooterSet, y as IndentFormatting, I as InsertableContentControlType, a2 as NumberingRef, a3 as PageMargins, P as Paragraph, a4 as ParagraphDisagreements, z as ParagraphFlags, a5 as ParagraphFormatCommand, A as ParagraphTabStop, a6 as Point, a7 as Rect, p as Revision, F as RevisionType, aa as Run, k as RunFormatting, G as Section, J as SectionProperties, ab as SelectionPin, K as StyleDefinition, S as StyleDefinitions, T as Table, ac as TableCell, ad as TableRow, L as Theme, M as ThemeColorScheme, ae as Unsubscribe, af as Watermark } from '../types-barrel-DuC5QBNC.js';
+import '../editor-scope-7o9xweiJ.js';

package/dist/{custom-node-writes-Vzpq9I8_.d.ts → custom-node-writes-Bn6uciLb.d.ts}

@@ -1,5 +1,5 @@
-import { Q as OoxmlPackage, O as OoxmlPart, N as OoxmlNode, a5 as TreeOpRejection } from './types-barrel-BFKR8Pzp.js';
-import { e as TreeModelChange, f as TreeDocumentStore } from './tree-package-fragment-DYZIk1rY.js';
+import { Q as OoxmlPackage, O as OoxmlPart, N as OoxmlNode, av as TreeOpRejection } from './types-barrel-DuC5QBNC.js';
+import { e as TreeModelChange, f as TreeDocumentStore } from './tree-package-store-CovjNARF.js';
 
 /** Which of a family's four faces an embedded font relationship supplies. */
 type FontStyleKey = 'regular' | 'bold' | 'italic' | 'boldItalic';

package/dist/diagnostic-context-B8M79cfK.d.ts

@@ -0,0 +1,30 @@
+import { D as DiagnosticErrorName, a as DocumentPartKind } from './diagnostic-hints-BeVjfNOv.js';
+
+/**
+ * Every engine reason a diagnostic can carry as its `cause`. Causes are the engine's own
+ * reasons and can change between engine versions; match on the public `code`, and read the
+ * `cause` when you report or fix a failure.
+ *
+ * @public
+ */
+declare function diagnosticCauses(): readonly string[];
+/**
+ * The engine reason token in a refusal reason, or undefined when the reason is not one the
+ * engine knows, such as a sentence. Only the token before a colon counts; the detail after it
+ * can name parts of the file and is never returned.
+ */
+declare function diagnosticCause(reason: string | undefined): string | undefined;
+/** The cause of a failure the engine did not name: an exception. */
+declare function exceptionCause(): string;
+/**
+ * The class of an exception, never its message. A subclass with its own name, which a host or a
+ * file could shape, reports `'other'`.
+ */
+declare function diagnosticErrorName(error: unknown): DiagnosticErrorName;
+/**
+ * The role of the part a failure names, from the part name at the start of a refusal detail.
+ * The name itself never leaves this function. Undefined when there is no detail.
+ */
+declare function documentPartKind(detail: string | undefined): DocumentPartKind | undefined;
+
+export { diagnosticCause as a, diagnosticErrorName as b, documentPartKind as c, diagnosticCauses as d, exceptionCause as e };